Developer CD Series 1996 April: Mac OS SDK/Dev.CD Apr 96 SDK/Dev.CD Apr 96 SDK1.toast/Development Kits (Disc 1)/OpenDoc/Sample Code/Sample Editors⁄Viewers/SamplePart (C)/Source/SamplePart.c

Text File | 1995-12-08 | 136.9 KB | 4,629 lines | [TEXT/MPS ]

/*------------------------------------------------------------------------------

    File:            SamplePart.c

    Written by:        Steve Smith and Andrey Dolgachev

    Copyright:        © 1995 by Apple Computer, Inc., all rights reserved.

    Description:    SamplePart demonstrates the most basic functions and
                    responsibilities of an OpenDoc™ leaf part.


    Demonstrates:    The following recipes were used in implementing the
                    SamplePart:
                     1. Open
                     2. Adding A Display Frame
                     3. Adding A Facet
                     4. Part Drawing
                     5. Refcounting Geometry
                     6. ViewTypes & Presentations
                     7. Display Frame 'ternalization
                     8. Part Init & Externalization
                     9. Part Init & partWrapper
                    10. Part Storage Model
                    11. Persistent Reference
                    12. RefCounting
                    13. Storage Unit
                    14. Activation
                    15. Basic Event Handling
                    16. Menus
                    17. Windows & Dialogs
                    18. Exception Handling
                    19. Memory Manager
                    20. Using Resources


    Notes:


    Known Problems:    <none>

------------------------------------------------------------------------------*/

// Notification that this is a SOM source file
#define SampleCode_SamplePart_Class_Source

// define unscore (_) field names
#define VARIABLE_MACROS

// -- Compiler/Preprocessor Switches --

#ifndef _COMPILERDEFS_
#include <CompDefs.h>
#endif

// -- OpenDoc Utilities --

#ifndef _EXCEPT_
// Exceptions define several important macros (ie. CHECKENV)
// which are used in the SOM method dispatch glue. If Except.h
// is not included early enough, exceptions may not be thrown
// correctly when returning from a SOM method with the "ev" parameter set.
#include <Except.h>
#endif

// -- SamplePart Includes --

#ifndef _SAMPLEPARTGLOBALS_
#include <SamplePartGlobals.h>
#endif

#ifndef _SAMPLEPARTDEF_
#include <SamplePartDef.h>
#endif

#ifndef _SAMPLEPARTUTILS_
#include <SamplePartUtils.h>
#endif

#ifndef SOM_SampleCode_SamplePart_ih
#include <SamplePart.ih>
#endif

// -- OpenDoc Includes --

#ifndef _ODTYPES_
#include <ODTypes.h>
#endif

#ifndef SOM_ODPart_h
#include <Part.h>
#endif

#ifndef SOM_ODFacet_h
#include <Facet.h>
#endif

#ifndef SOM_ODFrame_h
#include <Frame.h>
#endif

#ifndef SOM_ODFrameFacetIterator_h
#include <FrFaItr.h>
#endif

#ifndef SOM_ODArbitrator_h
#include <Arbitrat.h>
#endif

#ifndef SOM_Module_OpenDoc_Foci_defined
#include <Foci.h>
#endif

#ifndef SOM_ODShape_h
#include <Shape.h>
#endif

#ifndef SOM_Module_OpenDoc_StdProps_defined
#include <StdProps.h>
#endif

#ifndef SOM_Module_OpenDoc_StdTypes_defined
#include <StdTypes.h>
#endif

#ifndef SOM_Module_OpenDoc_StdDefs_defined
#include <StdDefs.h>
#endif

#ifndef SOM_Module_OpenDoc_Commands_defined
#include <CmdDefs.h>
#endif

#ifndef SOM_ODDraft_h
#include <Draft.h>
#endif

#ifndef SOM_ODStorageUnit_h
#include <StorageU.h>
#endif

#ifndef SOM_ODStorageUnitView_h
#include <SUView.h>
#endif

#ifndef SOM_ODTransform_h
#include <Trnsform.h>
#endif

#ifndef SOM_ODFocusSet_h
#include <FocusSet.h>
#endif

#ifndef SOM_ODMenuBar_h
#include <MenuBar.h>
#endif

#ifndef SOM_ODWindow_h
#include <Window.h>
#endif

#ifndef SOM_ODWindowState_h
#include <WinStat.h>
#endif

#ifndef SOM_ODSession_h
#include <ODSessn.h>
#endif

#ifndef SOM_ODTypeList_h
#include <TypeList.h>
#endif

#ifndef SOM_ODTypeListIterator_h
#include <TypLsItr.h>
#endif

// -- OpenDoc Utilities --

#ifndef _ITEXT_
#include <IText.h>
#endif

#ifndef _FOCUSLIB_
#include <FocusLib.h>
#endif

#ifndef _USERSRCM_
#include <UseRsrcM.h>
#endif

#ifndef _ODMEMORY_
#include <ODMemory.h>
#endif

#ifndef _ISOSTR_
#include <ISOStr.h>
#endif

#ifndef _ODUTILS_
#include <ODUtils.h>
#endif

#ifndef _STDTYPIO_
#include <StdTypIO.h>
#endif

#ifndef _WINUTILS_
#include <WinUtils.h>
#endif

#ifndef _PLFMDEF_
#include <PlfmDef.h>
#endif

// -- Macintosh Includes --

#ifndef __ERRORS__
//#include <Errors.h>
#endif

#ifndef __RESOURCES__
#include <Resources.h>
#endif

#ifndef __DIALOGS__
#include <Dialogs.h>
#endif

#ifndef __ICONS__
#include <Icons.h>
#endif

#ifndef __QUICKDRAW__
#include <Quickdraw.h>
#endif

#ifndef __GXMATH__
#include <GXMath.h>
#endif

#pragma segment SamplePart


//==============================================================================
// SamplePart
//==============================================================================

//------------------------------------------------------------------------------
// Method:        somInit
// Origin:        SOMObject
//
// Description:    This is the SOM equivalent of a C++ class constructor.
//                In this routine, you should call your parent class's
//                somInit (constructor) function and initialize your
//                internal fields.
//
// Warnings:    You are not allowed to throw an exception from this
//                method.
//------------------------------------------------------------------------------

SOM_Scope    void
SOMLINK        SamplePart__somInit
            (
                SampleCode_SamplePart*        somSelf
            )
{
    SampleCode_SamplePartMethodDebug("SamplePart","somInit");

    // somInit and somUninit methods behave like C++ constructors in that the
    // inherited methods are called automatically.
    // Thus, there is no need to call the parent class' somInit or somUninit.

    // There is also no need to set instance variables to zero/NULL
    // since SOM guarantees that a newly constructed object is zeroed.

    // Lastly, it is not valid to perform any operation here which may throw
    // an exception.
}

//--------------------------------------------------------------------
// Method:        somUninit
// Origin:        SOMObject
//
// Description:    This is the SOM equivalent of a C++ class destructor.
//                In this routine, you should clean up any internal
//                fields which were not cleaned up in the ReleaseAll and
//                Release methods; and finally call you parent class's
//                somUninit (destructor) function.
//
// Warnings:    You are not allowed to throw an exception from this
//                method.
//--------------------------------------------------------------------

SOM_Scope    void
SOMLINK        SamplePart__somUninit
            (
                SampleCode_SamplePart*        somSelf
            )
{
    SampleCode_SamplePartMethodDebug("SamplePart","somUninit");
}

//==============================================================================
#pragma mark    • Initialization •
//==============================================================================

//------------------------------------------------------------------------------
// Method:        InitPart
// Origin:        ODPart
//
// Description:    This method is called when a new instance of this part is being
//                created. The part should prepare itself to run.
//
// Warning:        It is not appropriate to require user iteraction while
//                stationery is being created. Do not present the user with error
//                dialogs or splash screens from this method.
//------------------------------------------------------------------------------

SOM_Scope    void
SOMLINK        SamplePart__InitPart
            (
                SampleCode_SamplePart*        somSelf,
                Environment*                ev,
                ODStorageUnit*                storageUnit,
                ODPart*                        partWrapper
            )
{
    SampleCode_SamplePartData *somThis = SampleCode_SamplePartGetData(somSelf);
    SampleCode_SamplePartMethodDebug("SamplePart","InitPart");

    SOM_TRY
        // We must call the initialize method of our parent PersistentObject
        // class to generate the appropriate time/date stamp on our
        // part's storage unit.
        SampleCode_SamplePart_parent_ODPart_InitPart(somSelf,ev,storageUnit,partWrapper);
        CHECK_ENV(ev);

        // To allow editor swapping (translation) at runtime, OpenDoc requires
        // that we pass in a "reference" to ourselves when interacting with the
        // API (ie. WindowState::RegisterWindow(), Dispatcher::RegisterIdle, etc).
        // The "partWrapper" passed to us here and in InitPartFromStorage is the
        // "reference" OpenDoc is asking us to use.
        _fSelf = partWrapper;

        // We are being created, either as part of generating stationery or
        // by some editor instantiating the part, so the destination storage
        // must be writeable.
        _fReadOnlyStorage = kODFalse;

        // Call the common initialization code to get set up.
        _Initialize(somSelf, ev);
        CHECK_ENV(ev);

        // Since we have just been created, our state/content info has
        // never been written out, so setting our "dirty" flag will
        // give us a chance to do that.
        _SetDirty(somSelf, ev);
        CHECK_ENV(ev);

    SOM_CATCH_ALL
    SOM_ENDTRY
}

//------------------------------------------------------------------------------
// Method:        InitPartFromStorage
// Origin:        ODPart
//
// Description:    This method is called when a document/stationery is being opened
//                or when the part is internalized by its containing part. The
//                part should merely read in the saved state/content and
//                initialize itself. The part must not alter its storage unit;
//                otherwise, the "Save" menu item becomes enabled without the user
//                actually having made a change to the document.
//------------------------------------------------------------------------------

SOM_Scope    void
SOMLINK        SamplePart__InitPartFromStorage
            (
                SampleCode_SamplePart*        somSelf,
                Environment*                ev,
                ODStorageUnit*                storageUnit,
                ODPart*                        partWrapper
            )
{
    SampleCode_SamplePartData *somThis = SampleCode_SamplePartGetData(somSelf);
    SampleCode_SamplePartMethodDebug("SamplePart","InitPartFromStorage");

    SOM_TRY

        // We must call the initialize method of our parent PersistentObject
        // class to generate the appropriate time/date stamp on our
        // part's storage unit.
        SampleCode_SamplePart_parent_ODPart_InitPartFromStorage
                            (somSelf,ev,storageUnit,partWrapper);
        CHECK_ENV(ev);

        // To allow editor swapping (translation) at runtime, OpenDoc requires
        // that we pass in a "reference" to ourselves when interacting with the
        // API (ie. WindowState::RegisterWindow(), Dispatcher::RegisterIdle, etc).
        // The "partWrapper" passed to us here and in InitPartFromStorage is the
        // "reference" OpenDoc is asking us to use.
        _fSelf = partWrapper;

        // Are we being opened from a read-only draft? If so, we cannot
        // write anything back out to our storage unit.

        {
            ODDraft* draft = ODGetDraftFromPart(ev,_fSelf);
            _fReadOnlyStorage = ( ODDraft_GetPermissions(draft, ev) < kODDPSharedWrite );
            CHECK_ENV(ev);
        }

        // Call the common initialization code to get set up.
        _Initialize(somSelf, ev);
        CHECK_ENV(ev);

        // Read in the state the part was in when it was last Externalized.
        // This allows the part to present the same "environment" the user
        // had the part set up in the last time it was edited.
        _InternalizeStateInfo(somSelf, ev, storageUnit);
        CHECK_ENV(ev);

        // Read in the contents for your part editor.
        _InternalizeContent(somSelf, ev, storageUnit);
        CHECK_ENV(ev);

    SOM_CATCH_ALL
    SOM_ENDTRY
}

//------------------------------------------------------------------------------
// Method:        Initialize
// Origin:        SamplePart
//
// Description:    This method is called during the initialization of the part. The
//                method is used to initialize all fields of the part and to
//                convert ISO types to tokens for faster comparisons throughout
//                the code.
//------------------------------------------------------------------------------

SOM_Scope    void
SOMLINK        SamplePart__Initialize
            (
                SampleCode_SamplePart*        somSelf,
                Environment*                ev
            )
{
    SampleCode_SamplePartData *somThis = SampleCode_SamplePartGetData(somSelf);
    SampleCode_SamplePartMethodDebug("SamplePart","Initialize");

    SOM_TRY

        ODSession*        session = kODNULL;
        ODArbitrator*    arbitrator = kODNULL;
        ODWindowState*    windowState = kODNULL;

        // Create a list to keep track of the facets we are being
        // displayed in. Also used for maintenance (i.e., Purging memory).
        _fDisplayFrames = CLinkedList_Create();

        // First check to see if the library's global variables have
        // been initialized (meaning another part instantiation is already
        // running).

        if ( gGlobalsUsageCount == 0 )
        {
            // Grab a reference to the Session object. This is merely for
            // convenience.
            session = ODGetSessionFromPart(ev,_fSelf);
            CHECK_ENV(ev);

            // Create our globals space. We store the globals in a struct so
            // that we can put them in temp mem. Otherwise, CFM loads the globals
            // with the data fragment of a CFM library in the application heap.
            gGlobals = newGlobals();

            // It is required that parts instantiate their menu bars from
            // the base OpenDoc menu bar. This maintains consistency in the
            // default menu items and their placement.
            // Since the object is a copy, we can add and subtract menus and
            // items without affecting other running parts.
            windowState = ODSession_GetWindowState(session, ev);
            gGlobals->fMenuBar = ODWindowState_CopyBaseMenuBar(windowState, ev);
            CHECK_ENV(ev);

            // We will be using the above foci (shared resources) in this
            // part. For convenience, we tokenize the values here and store
            // them for equivalence tests in the activation methods.
            gGlobals->fSelectionFocus = ODSession_Tokenize(session, ev, kODSelectionFocus);
            gGlobals->fMenuFocus      = ODSession_Tokenize(session, ev, kODMenuFocus);
            gGlobals->fModalFocus     = ODSession_Tokenize(session, ev, kODModalFocus);

            // Also for convenience, we tokenize our part's main presentation
            // and the standard view types.
            gGlobals->fMainPresentation = ODSession_Tokenize(session, ev, kMainPresentation);

            gGlobals->fFrameView        = ODSession_Tokenize(session, ev, kODViewAsFrame);
            gGlobals->fLargeIconView = ODSession_Tokenize(session, ev, kODViewAsLargeIcon);
            gGlobals->fSmallIconView = ODSession_Tokenize(session, ev, kODViewAsSmallIcon);
            gGlobals->fThumbnailView = ODSession_Tokenize(session, ev, kODViewAsThumbnail);

            // Lastly, we will package the menu and selection focus
            // so that we can request the "set" at activation time.
            arbitrator = ODSession_GetArbitrator(session, ev);
            gGlobals->fUIFocusSet = ODArbitrator_CreateFocusSet(arbitrator, ev);
            CHECK_ENV(ev);
            ODFocusSet_Add(gGlobals->fUIFocusSet, ev, gGlobals->fMenuFocus);
            ODFocusSet_Add(gGlobals->fUIFocusSet, ev, gGlobals->fSelectionFocus);
            CHECK_ENV(ev);

            // Determine what Script/Language the part is localized for.
            // This is important/necessary for creating OpenDoc's text objects.
            GetEditorScriptLanguage(ev, &gGlobals->fEditorsScript, &gGlobals->fEditorsLanguage);

            // The first client of the global variables is running.
            gGlobalsUsageCount = 1;
        }
        else
        // If the globals have been initialized, we just bump the "usage" count so
        // that we know how many part instances are using them.
        {
            gGlobalsUsageCount++;
        }

    SOM_CATCH_ALL
        gGlobalsUsageCount = 0;
    SOM_ENDTRY
}

//==============================================================================
#pragma mark    • Storage •
//==============================================================================

//------------------------------------------------------------------------------
// Method:        Release
// Origin:        ODPart
//
// Description:    This method is called each time an object releases a reference
//                to the part. If the refcount falls to 0, the part should
//                release the fSelf part reference.
//
// Warning:        If the part releases any other object when the refcount falls to
//                zero, it will need to override the IncrementRefCount method so
//                that the object can be referenced again if the parts refcount
//                should be incremented before it is deleted.
//------------------------------------------------------------------------------

SOM_Scope    void
SOMLINK        SamplePart__Release
            (
                SampleCode_SamplePart*        somSelf,
                Environment*                ev
            )
{
    SampleCode_SamplePartData *somThis = SampleCode_SamplePartGetData(somSelf);
    SampleCode_SamplePartMethodDebug("SamplePart","Release");

    SOM_TRY

        SampleCode_SamplePart_parent_ODPart_Release(somSelf,ev);
        CHECK_ENV(ev);

        if ( ODPart_GetRefCount(_fSelf, ev) == 0 )
        {
            ODDraft* draft = ODGetDraftFromPart(ev,_fSelf);
            ODDraft_ReleasePart(draft, ev, _fSelf);
        }

    SOM_CATCH_ALL
    SOM_ENDTRY
}

//--------------------------------------------------------------------
// Method:        ReleaseAll
// Origin:        ODPersistentObject
//
// Description:    This method is called just prior to the part being
//                deleted by the Draft. The part must release all
//                references to all refcounted objects it has stored
//                internally; not doing so, will cause an "invalid ref
//                count" exception/error.
//-------------------------------------------------------------------

SOM_Scope    void
SOMLINK        SamplePart__ReleaseAll
            (
                SampleCode_SamplePart*        somSelf,
                Environment*                ev
            )
{
    SampleCode_SamplePartData *somThis = SampleCode_SamplePartGetData(somSelf);
    SampleCode_SamplePartMethodDebug("SamplePart","ReleaseAll");

    SOM_TRY
        // If the last part instance using the globals is released,
        // we need to clean up and delete the globals.

        if ( --gGlobalsUsageCount == 0 )
        {
            // Release the menubar.
            ODReleaseObject(ev, gGlobals->fMenuBar);

            // Delete the focusSet
            ODDeleteObject_C(gGlobals->fUIFocusSet);

            // Release the thumbnail (PICT) resource.
            if ( gGlobals->fThumbnail )
            {
                ReleaseResource(gGlobals->fThumbnail);
                gGlobals->fThumbnail = kODNULL;
            }

            // Now, clean up the globals struct.
            deleteGlobals(&gGlobals);
        }

        // Remove and release our display frames.
        if ( _fDisplayFrames)
        {
            CLink* link;
            for ( link = CLinkedList_First(_fDisplayFrames);
                 CLink_Content(link);
                 link = CLink_Next(link) )
            {
                CFrameProxy* proxy = (CFrameProxy*) CLink_Content(link);
                // Delete the proxy object and its contents. The frame's
                // refcount will be decremented in the proxy destructor.
                link = link->prev;
                CLinkedList_Remove(_fDisplayFrames, proxy);
                CFrameProxy_Delete(&proxy, ev);
            }
        }

        // Delete the display frame collection.
        CLinkedList_Delete(_fDisplayFrames);

        SampleCode_SamplePart_parent_ODPart_ReleaseAll(somSelf,ev);

    SOM_CATCH_ALL
        // If something goes wrong while we are cleaning up, we must
        // let the Draft know because there may be some refcounted objects
        // which did not get released. Not to mention, possible memory
        // leaks.
    SOM_ENDTRY
}

//------------------------------------------------------------------------------
// Method:        Purge
// Origin:        ODObject
//
// Description:    This method is called when the OpenDoc requires more memory for
//                allocating objects and just before a part is deleted. The part
//                should free up as much memory as it can.
//
//                The part determines which views are being "used" in its display
//                frames. The resources for the unused view types are then purged.
//------------------------------------------------------------------------------

SOM_Scope    ODSize
SOMLINK        SamplePart__Purge
            (
                SampleCode_SamplePart*        somSelf,
                Environment*                ev,
                ODSize                        size /* unused */
            )
{
    ODSize bytesFreed = 0;

    SampleCode_SamplePartData *somThis = SampleCode_SamplePartGetData(somSelf);
    SampleCode_SamplePartMethodDebug("SamplePart","Purge");

    SOM_TRY

        ODBoolean    usingThumbnail  = kODFalse;
        CLink*        link;

        // Purge is called during the creation of stationery. However,
        // we have not created our internal display frames list, so
        // trying to iterate over it would be fatal.
        if ( _fDisplayFrames == kODNULL) return 0;

        // Iterate over the frames we are displayed through and determine which
        // view types are currently in use.

        for ( link = CLinkedList_First(_fDisplayFrames);
              CLink_Content(link);
              link = CLink_Next(link) )
        {
            // If the display frame is real (has been "connected" or was "added")
            // get it's view type; otherwise, ignore it.
            CFrameProxy* proxy = (CFrameProxy*) CLink_Content(link);
            if ( CFrameProxy_FrameIsLoaded(proxy, ev) )
            {
                ODTypeToken    frameView;
                ODFrame*    frame = CFrameProxy_GetFrame(proxy, ev);
                CHECK_ENV(ev);

                frameView = ODFrame_GetViewType(frame, ev);

                if ( frameView == gGlobals->fThumbnailView )
                    usingThumbnail = kODTrue;

                // Release the frame reference, but don't get rid of the
                // proxy object because we're not done with the frame. If
                // all parts release their references the frame will be
                // purged from memory.
                CFrameProxy_Purge(proxy, ev);
            }
        }

        // Based on the usage of the supported view types, free up as much
        // memory as possible.

        if ( !usingThumbnail && (gGlobals->fThumbnail != kODNULL) )
        {
            bytesFreed += (ODSize) ODGetHandleSize(gGlobals->fThumbnail);
            ReleaseResource(gGlobals->fThumbnail);
            gGlobals->fThumbnail = kODNULL;
        }

    SOM_CATCH_ALL
        bytesFreed = 0;
    SOM_ENDTRY

    return bytesFreed;
}

//------------------------------------------------------------------------------
// Method:        InternalizeStateInfo
// Origin:        SamplePart
//
// Description:    This method is used to read in "state" information for the part.
//                This is information related to the workings of the part editor,
//                not the content.
//
//                The part rights out a list of weak references to its display
//                frames. This allows the part to reuse the same display frames
//                each time the document is opened. Those references are read
//                back in and validated here.
//
// Note:        The function StorageUnitGetValue simplifies the use of
//                ODByteArrary, which is required the StorageUnit interface. Look
//                in StorUtil.h/cpp for an example of using the ODByteArray struct.
//------------------------------------------------------------------------------

SOM_Scope    void
SOMLINK        SamplePart__InternalizeStateInfo
            (
                SampleCode_SamplePart*        somSelf,
                Environment*                ev,
                ODStorageUnit*                storageUnit
            )
{
    SampleCode_SamplePartData *somThis = SampleCode_SamplePartGetData(somSelf);
    SampleCode_SamplePartMethodDebug("SamplePart","InternalizeStateInfo");

    SOM_TRY

        // Internalize the part's display frame list.

        if ( ODStorageUnit_Exists(storageUnit, ev, kODPropDisplayFrames,
                                        kODWeakStorageUnitRefs, 0) )
        {
            ODULong size;
            ODULong offset;

            ODStorageUnit_Focus(storageUnit, ev, kODPropDisplayFrames,
                                    kODPosUndefined, kODWeakStorageUnitRefs, 0,
                                    kODPosUndefined);
            CHECK_ENV(ev);

            size = ODStorageUnit_GetSize(storageUnit, ev);
            CHECK_ENV(ev);
            ODStorageUnit_SetOffset(storageUnit, ev, 0);
            CHECK_ENV(ev);

            for ( offset = 0; offset < size; offset += kODStorageUnitRefSize )
            {
                TRY
                    ODStorageUnitRef weakRef;

                    StorageUnitGetValue_C(storageUnit, ev, kODStorageUnitRefSize, (ODPtr)&weakRef);
                    CHECK_ENV(ev);

                    if ( ODStorageUnit_IsValidStorageUnitRef(storageUnit, ev,
                            weakRef) )
                    {
                        CFrameProxy* proxy;
                        ODID id;

                        // We lazily internalize our display frames, meaning we don't "get"
                        // the frame until we absolutely need it. This reduces the time
                        // to internalize the part and the amount of memory needed.

                        // Convert the reference into a runtime id.
                        id = ODStorageUnit_GetIDFromStorageUnitRef(storageUnit, ev,
                                                                        weakRef);
                        CHECK_ENV(ev);
                        // Acquire a new frame to support the lazy internalization.
                        proxy = CFrameProxy_Create();
                        CFrameProxy_InitFrameProxyWithID(proxy, id,
                                                ODGetDraftFromSU(ev,storageUnit));

                        // Add the frame to the display frame collection.
                        CLinkedList_Add(_fDisplayFrames, (ODPtr)proxy);
                    }
                    CHECK_ENV(ev);
                CATCH_ALL
                    // consume exception
                ENDTRY
            }
        }
        CHECK_ENV(ev);

    SOM_CATCH_ALL
    SOM_ENDTRY
}

//------------------------------------------------------------------------------
// Method:        InternalizeContent
// Origin:        SamplePart
//
// Description:    This method is called during initialization of the part from an
//                existing document. The content of the part should be read in.
//
//                The part has no intrinsic content, so the part does nothing.
//                The method is here for completeness.
//------------------------------------------------------------------------------

SOM_Scope    void
SOMLINK        SamplePart__InternalizeContent
            (
                SampleCode_SamplePart*        somSelf,
                Environment*                ev,
                ODStorageUnit*                storageUnit
            )
{
    SampleCode_SamplePartMethodDebug("SamplePart","InternalizeContent");
}

//------------------------------------------------------------------------------
// Method:        CloneInto
// Origin:        ODPersistentObject
//
// Description:    This method is called during cloning, typically during data
//                interchange operations (ie. Cut/Paste). The part should
//                write out its current state and content.
//------------------------------------------------------------------------------

SOM_Scope    void
SOMLINK        SamplePart__CloneInto
             (
                SampleCode_SamplePart*        somSelf,
                Environment*                ev,
                ODDraftKey                    key,
                ODStorageUnit*                destinationSU,
                ODFrame*                    initiatingFrame
            )
{
    SampleCode_SamplePartMethodDebug("SamplePart","CloneInto");

    SOM_TRY

        // This calls back up to the persistent object parent
        // class which copies over our timedate stamp and last modified
        // information.
        SampleCode_SamplePart_parent_ODPart_CloneInto
                (somSelf,ev,key,destinationSU,initiatingFrame);
        CHECK_ENV(ev);

        // We must first verify that we've never written to this storage unit.
        // If we have, we should do nothing, otherwise we need to write out
        // the current state of the part content.

        if ( ODStorageUnit_Exists(destinationSU, ev, kODPropContents,
                kSamplePartKind, 0) == kODFalse )
        {
            // Add the properties we need to successfully externalize
            // ourselves into the destination storage unit.
            _CheckAndAddProperties(somSelf, ev, destinationSU);
            CHECK_ENV(ev);

            // Write out the part's state information.
            _ExternalizeStateInfo(somSelf, ev, destinationSU, key, initiatingFrame);
            CHECK_ENV(ev);

            // Write out the part's content.
            _ExternalizeContent(somSelf, ev, destinationSU, key, initiatingFrame);
            CHECK_ENV(ev);
        }

    SOM_CATCH_ALL
    SOM_ENDTRY
}

//------------------------------------------------------------------------------
// Method:        Externalize
// Origin:        ODPersistentObject
//
// Description:    This method is called when the user saves the document. The part
//                should write out its state and content if changes have occurred
//                and if our storage is writeable.
//
// Note:        The part must call its parent class behavior because one or more
//                of our parent classes contains implementation. This is done in
//                the SOM class.
//------------------------------------------------------------------------------

SOM_Scope    void
SOMLINK        SamplePart__Externalize
            (
                SampleCode_SamplePart*        somSelf,
                Environment*                ev
            )
{
    ODStorageUnit* storageUnit;

    SampleCode_SamplePartData *somThis = SampleCode_SamplePartGetData(somSelf);
    SampleCode_SamplePartMethodDebug("SamplePart","Externalize");

    SOM_TRY
        // First ask our parent classes to externalize.
        SampleCode_SamplePart_parent_ODPart_Externalize(somSelf,ev);
        CHECK_ENV(ev);

        if ( _fDirty && !_fReadOnlyStorage)
        {
            // Get our storage unit.
            storageUnit = ODPart_GetStorageUnit(somSelf, ev);
            CHECK_ENV(ev);

            // Verify that the storage unit has the appropriate properties
            // and values to allow us to run. If not, add them.
            _CheckAndAddProperties(somSelf, ev, storageUnit);
            CHECK_ENV(ev);

            // Verify that there are no "bogus" values in the Content
            // property.
            _CleanseContentProperty(somSelf, ev, storageUnit);
            CHECK_ENV(ev);

            // Write out the part's state information.
            _ExternalizeStateInfo(somSelf, ev, storageUnit, kODNULLKey, kODNULL);
            CHECK_ENV(ev);

            // Write out the part's content.
            _ExternalizeContent(somSelf, ev, storageUnit, kODNULLKey, kODNULL);
            CHECK_ENV(ev);

            // Flag our part as no longer being dirty.
            _fDirty = kODFalse;
        }

    SOM_CATCH_ALL
        // Alert the user of the problem.
        _DoDialogBox(somSelf, ev, kODNULL, kErrorBoxID, kErrExternalizeFailed);
        // Change the exception value, so the DocShell doesn't display an
        // error dialog.
        ODSetSOMException(ev, kODErrAlreadyNotified, kODNULL);
    SOM_ENDTRY
}

//------------------------------------------------------------------------------
// Method:        ExternalizeKinds
// Origin:        ODPart
//
// Description:    This method is called when the user wants to save the document
//                with multiple representations of the data. This is especially
//                useful for increasing the portability of documents
//                cross-platform.
//
//                A part should verify each kind is valid, that it exists in
//                the content property in the correct order, and write the data.
//------------------------------------------------------------------------------

SOM_Scope    void
SOMLINK        SamplePart__ExternalizeKinds(SampleCode_SamplePart *somSelf,
        Environment *ev,
        ODTypeList* kindset)
{
    SampleCode_SamplePartData *somThis = SampleCode_SamplePartGetData(somSelf);
    SampleCode_SamplePartMethodDebug("SamplePart","ExternalizeKinds");

    SOM_TRY

        if ( !_fReadOnlyStorage )
        {
            ODType                kind;
            ODBoolean            preferredKindWritten = kODFalse;
            ODTypeListIterator* tliter = kODNULL;
            ODStorageUnit*        storageUnit;

            ODVolatile(tliter);

            // Get our storage unit.
            storageUnit = ODPart_GetStorageUnit(somSelf, ev);
            CHECK_ENV(ev);

            // Verify that the storage unit has the appropriate properties
            // and values to allow us to run. If not, add them.
            _CheckAndAddProperties(somSelf, ev, storageUnit);
            CHECK_ENV(ev);

            // Verify that there are no "bogus" values in the Content
            // property.
            _CleanseContentProperty(somSelf, ev, storageUnit);
            CHECK_ENV(ev);

            // Iterate over the kindset and write out the content types
            // that we support.
            tliter = ODTypeList_CreateTypeListIterator(kindset, ev);
            CHECK_ENV(ev);

            TRY
                for ( kind = ODTypeListIterator_First(tliter, ev);
                        ODTypeListIterator_IsNotComplete(tliter, ev);
                        kind = ODTypeListIterator_Next(tliter, ev) )
                {

                    // Check to see if this is a kind we support. If so, write it.
                    if ( ODISOStrCompare(kind, kSamplePartKind) == 0 )
                    {
                        // Write out the part's content.
                        _ExternalizeContent(somSelf, ev, storageUnit,
                                                                kODNULLKey, kODNULL);
                        // This is our preferrend kind so we don't need to write it again.
                        // Part editors with more than one kind need to test each kind
                        // against the preferred kind to make sure it's been written.
                        preferredKindWritten = kODTrue;
                    }
                }
                CHECK_ENV(ev);
                // Delete the iterator;
                ODDeleteObject_C(tliter);
            CATCH_ALL
                // Delete the iterator;
                ODDeleteObject_C(tliter);
                RERAISE;
            ENDTRY

            // Write out the part's state information.
            _ExternalizeStateInfo(somSelf, ev, storageUnit, kODNULLKey, kODNULL);
            CHECK_ENV(ev);

            // Even if the kind set contains no types we support, we must at least
            // write out our current "preferred" kind.
            if ( preferredKindWritten == kODFalse )
            {
                // Write out the part's preferred content kind, which, for SamplePart,
                // is the only kind.
                _ExternalizeContent(somSelf, ev, storageUnit, kODNULLKey, kODNULL);
                CHECK_ENV(ev);
            }
        }

    SOM_CATCH_ALL
    SOM_ENDTRY
}

//------------------------------------------------------------------------------
// Method:        ChangeKind
// Origin:        ODPart
//
// Description:    This method is called when the changes the part's primary kind
//                and/or when the part editor is switched via the Info dialog.
//
//                The editor should record the new "preferred" kind and change the
//                UI, if necessary, to allow editing of that kind. Don't write the
//                properties/values/data until the Externalize is called.
//------------------------------------------------------------------------------

SOM_Scope void  SOMLINK SamplePart__ChangeKind(SampleCode_SamplePart *somSelf,
        Environment *ev,
        ODType kind)
{
    SampleCode_SamplePartMethodDebug("SamplePart","ChangeKind");

    SOM_TRY
        // SamplePart only has one kind, but we need to make sure the "Preferred Kind"
        // property has the correct value.
        if ( ODISOStrCompare(kind, kSamplePartKind) == 0 )
        {
            // Get our storage unit.
            ODStorageUnit* storageUnit = ODPart_GetStorageUnit(somSelf, ev);

            TRY
                ODSetISOStrProp(ev, storageUnit, kODPropPreferredKind, kODISOStr, kSamplePartKind);

                // Changing our kind dirties our content.
                _SetDirty(somSelf, ev);

                // Immediately externalize ourselves in the "new" format.
                SamplePart__Externalize(somSelf, ev);
                CHECK_ENV(ev);

            CATCH_ALL
                // Remove the property and value if something went wrong.
                ODStorageUnit_Remove(storageUnit, ev);
            ENDTRY
        }
        else
            THROW(kODErrInvalidValueType);

    SOM_CATCH_ALL
    SOM_ENDTRY

}


//------------------------------------------------------------------------------
// Method:        ExternalizeStateInfo
// Origin:        SamplePart
//
// Description:    This method is called during externalization of the part. The
//                current "state" of the part should be written out. This "state"
//                information may be lost during Data Interchange operations, so
//                the part needs to recover gracefully if information is missing
//                or incomplete.
//
// Note:        The function StorageUnitSetValue is a macro which simplifies
//                the use of ODByteArrary, which is required by the StorageUnit
//                interface. Look in StorUtil.h/cpp for an example of using the
//                ODByteArray struct.
//------------------------------------------------------------------------------

SOM_Scope    void
SOMLINK        SamplePart__ExternalizeStateInfo
            (
                SampleCode_SamplePart*        somSelf,
                Environment*                ev,
                ODStorageUnit*                storageUnit,
                ODDraftKey                    key,
                ODFrame*                    scopeFrame
            )
{
    SampleCode_SamplePartData *somThis = SampleCode_SamplePartGetData(somSelf);
    SampleCode_SamplePartMethodDebug("SamplePart","ExternalizeStateInfo");

    SOM_TRY
        ODID                scopeFrameID;
        ODDraft*            fromDraft;
        CLink*                link;

        scopeFrameID = ( scopeFrame ? ODFrame_GetID(scopeFrame,ev) : kODNULLID );
        CHECK_ENV(ev);

        fromDraft = ODGetDraftFromPart(ev,_fSelf);
        CHECK_ENV(ev);

        // Externalize the part's display frame list.

        ODStorageUnit_Focus(storageUnit, ev, kODPropDisplayFrames, kODPosUndefined,
                                    kODWeakStorageUnitRefs, 0, kODPosUndefined);
        CHECK_ENV(ev);

        // Persistent object references are stored in a side table, rather than
        // in the property/value stream. Thus, deleting the contents of a value
        // will not "delete" the references previously written to that value. To
        // completely "delete" all references written to the value, we must
        // remove the value and add it back.
        ODStorageUnit_Remove(storageUnit, ev);
        CHECK_ENV(ev);

        ODStorageUnit_AddValue(storageUnit, ev, kODWeakStorageUnitRefs);
        CHECK_ENV(ev);

        for ( link = CLinkedList_First(_fDisplayFrames);
             CLink_Content(link);
             link = CLink_Next(link) )
        {
            ODID                frameID;
            CFrameProxy*        proxy;
            ODStorageUnitRef    weakRef;

            // Get the ID of the frame we are going to weakly reference.
            proxy = (CFrameProxy*) CLink_Content(link);
            frameID = CFrameProxy_GetID(proxy);

            // If a draft key exists, then we are being cloned to another draft.
            // We must "weak" clone our display frame and reference the cloned
            // frame. The part re-uses the frameID variable so there aren't two
            // different GetWeakStorageUnitRef calls.
            if ( key )
            {
                frameID = ODDraft_WeakClone(fromDraft, ev, key, frameID, kODNULLID, scopeFrameID);
                CHECK_ENV(ev);
            }

            // Write out weak references to each of the part's display frames.
            ODStorageUnit_GetWeakStorageUnitRef(storageUnit, ev, frameID, weakRef);
            CHECK_ENV(ev);

            StorageUnitSetValue_C(storageUnit, ev, kODStorageUnitRefSize, (ODPtr)&weakRef);
        }

    SOM_CATCH_ALL
    SOM_ENDTRY
}

//------------------------------------------------------------------------------
// Method:        ExternalizeContent
// Origin:        SamplePart
//
// Description:    This method is called during exteralization of the part. The
//                content of the part should be written out.
//
//                The part has no intrinsic content, so the part does nothing.
//                The method is here for completeness.
//------------------------------------------------------------------------------

SOM_Scope    void
SOMLINK        SamplePart__ExternalizeContent
            (
                SampleCode_SamplePart*        somSelf,
                Environment*                ev,
                ODStorageUnit*                storageUnit, /* unused */
                ODDraftKey                    key,         /* unused */
                ODFrame*                    scopeFrame /* unused */
            )
{
    SampleCode_SamplePartMethodDebug("SamplePart","ExternalizeContent");

    // You would write out your part's content after focusing to your
    // content property.

}

//------------------------------------------------------------------------------
// Method:        CleanseContentProperty
// Oringin:        SamplePart
//
// Description:    This method is called during exteralization of the part so that
//                the part can remove any value in the content property
//                that it cannot "accurately" write to.
//
// Note:        "Additional" values will be added to a part's content property
//                during Drag & Drop operations.
//------------------------------------------------------------------------------

SOM_Scope    void
SOMLINK        SamplePart__CleanseContentProperty
            (
                SampleCode_SamplePart*        somSelf,
                Environment*                ev,
                ODStorageUnit*                storageUnit
            )
{
    SampleCode_SamplePartData *somThis = SampleCode_SamplePartGetData(somSelf);
    SampleCode_SamplePartMethodDebug("SamplePart","CleanseContentProperty");

    SOM_TRY

        ODULong        numValues;
        ODULong        index;
        ODValueType    value;

        ODVolatile(value);

        ODStorageUnit_Focus(storageUnit, ev, kODPropContents, kODPosUndefined,
                                kODNULL, 0, kODPosAll);

        numValues = ODStorageUnit_CountValues(storageUnit, ev);

        for (index = numValues; index >= 1; index--)
        {
            // Index from n to 1 through the values.
            ODStorageUnit_Focus(storageUnit, ev, kODPropContents, kODPosUndefined,
                                    kODNULL, index, kODPosUndefined);

            TRY
                // Get the ISO type name for the value. The temp object
                // will automatically delete the returned value when this
                // scope is exited.
                value = ODStorageUnit_GetType(storageUnit, ev);

                // If the value type is not one we support, remove it.
                if ( ODISOStrCompare(value, kSamplePartKind) != 0 )
                    ODStorageUnit_Remove(storageUnit, ev);

                ODDisposePtr(value);

            CATCH_ALL
                ODDisposePtr(value);
                RERAISE;
            ENDTRY
        }

    SOM_CATCH_ALL
    SOM_ENDTRY
}

//------------------------------------------------------------------------------
// Method:        CheckAndAddProperties
// Origin:        SamplePart
//
// Description:    This method is called during externalization of the part to
//                verify that all the properties needed to persistently represent
//                the current running state of the part.
//
//                The part adds the default content property, a preferred editor
//                property (to aid in part binding), a display frames property.
//
// Note:        The function StorageUnitSetValue is a macro which simplifies
//                the use of ODByteArrary, which is required the StorageUnit
//                interface. Look in StorUtil.h/cpp for an example of using the
//                ODByteArray struct.
//------------------------------------------------------------------------------

SOM_Scope    void
SOMLINK        SamplePart__CheckAndAddProperties
            (
                SampleCode_SamplePart*        somSelf,
                Environment*                ev,
                ODStorageUnit*                storageUnit
            )
{
    SampleCode_SamplePartData *somThis = SampleCode_SamplePartGetData(somSelf);
    SampleCode_SamplePartMethodDebug("SamplePart","CheckAndAddProperties");

    SOM_TRY

        // Create our content property and preferred content property kind.

        if ( !ODStorageUnit_Exists(storageUnit, ev, kODPropContents, kODNULL, 0) )
            ODStorageUnit_AddProperty(storageUnit, ev, kODPropContents);
        if ( !ODStorageUnit_Exists(storageUnit, ev, kODPropContents, kSamplePartKind, 0) )
        {
            ODStorageUnit_Focus(storageUnit, ev, kODPropContents, kODPosUndefined, kODNULL, 0, kODPosAll);
            ODStorageUnit_AddValue(storageUnit, ev, kSamplePartKind);
        }

        // Since we are setting up the preferred kind property, we just write
        // out our default "kind" for the editor. We can write out the user
        // chosen kind in the ExternalizeStateInfo method.

        if ( !ODStorageUnit_Exists(storageUnit, ev, kODPropPreferredKind, kODNULL, 0) )
        {
            TRY
                ODSetISOStrProp(ev, storageUnit, kODPropPreferredKind, kODISOStr, kSamplePartKind);
            CATCH_ALL
                // Remove the property and value if something went wrong.
                ODStorageUnit_Remove(storageUnit, ev);
            ENDTRY
        }

        // Add our display frame list.

        if ( !ODStorageUnit_Exists(storageUnit, ev, kODPropDisplayFrames, kODNULL, 0) )
            ODStorageUnit_AddProperty(storageUnit, ev, kODPropDisplayFrames);
        if ( !ODStorageUnit_Exists(storageUnit, ev, kODPropDisplayFrames,
                    kODWeakStorageUnitRefs, 0) )
        {
            ODStorageUnit_Focus(storageUnit, ev, kODPropDisplayFrames, kODPosUndefined, kODNULL, 0, kODPosAll);
            ODStorageUnit_AddValue(storageUnit, ev, kODWeakStorageUnitRefs);
        }

    SOM_CATCH_ALL
    SOM_ENDTRY
}

//------------------------------------------------------------------------------
// Method:        SetDirty
// Origin:        SamplePart
//
// Description:    This method is called by the part when the content or state of
//                the part has been modified by the user and the "Save" menu item
//                should be enabled.
//------------------------------------------------------------------------------

SOM_Scope    void
SOMLINK        SamplePart__SetDirty
             (
                SampleCode_SamplePart*        somSelf,
                Environment*                ev
            )
{
    SampleCode_SamplePartData *somThis = SampleCode_SamplePartGetData(somSelf);
    SampleCode_SamplePartMethodDebug("SamplePart","SetDirty");

    SOM_TRY

        // There is no need to repeatedly tell the draft we have
        // changed; once is sufficient.
        if ( !_fDirty & !_fReadOnlyStorage)
        {
            ODDraft* draft = ODGetDraftFromPart(ev,_fSelf);
            ODDraft_SetChangedFromPrev(draft, ev);

            _fDirty = kODTrue;
        }

    SOM_CATCH_ALL
    SOM_ENDTRY
}

//------------------------------------------------------------------------------
// Method:        ReadPartInfo
//
// Description:    When a frame is being internalized by the Draft, it will ask the
//                owner (part) to read in its info annotation on the frame.
//
//                The part uses a helper struct to encapsulate the information
//                we store with each frame, so we let it internalize itself from
//                the storage unit view.
//------------------------------------------------------------------------------

SOM_Scope    ODInfoType
SOMLINK        SamplePart__ReadPartInfo
            (
                SampleCode_SamplePart*    somSelf,
                Environment*            ev,
                ODFrame*                frame,
                ODStorageUnitView*        storageUnitView
            )
{
    CFrameInfo* frameInfo = kODNULL;

    SampleCode_SamplePartData *somThis = SampleCode_SamplePartGetData(somSelf);
    SampleCode_SamplePartMethodDebug("SamplePart","ReadPartInfo");

    ODVolatile(frameInfo);

    SOM_TRY
        frameInfo = CFrameInfo_Create(ODGetSessionFromPart(ev,_fSelf));
        CFrameInfo_InitFromStorage(frameInfo, ev, storageUnitView);
        CHECK_ENV(ev);
    SOM_CATCH_ALL
        CFrameInfo_Delete( &frameInfo, ev );
    SOM_ENDTRY

    return (ODInfoType)frameInfo;
}

//------------------------------------------------------------------------------
// Method:        WritePartInfo
//
// Description:    When a frame is being externalized by the Draft, it
//                will ask the owner (part) to write out its info
//                annotation on the frame.
//
// Description:    When a frame is being externalized by the Draft, it will ask the
//                owner (part) to write out its info annotation on the frame.
//
//                The part uses a struct to encapsulate the information
//                we store with each frame, and we use a utility function to
//                externalize it to the storage unit view.
//------------------------------------------------------------------------------

SOM_Scope    void
SOMLINK        SamplePart__WritePartInfo
            (
                SampleCode_SamplePart*        somSelf,
                Environment*                ev,
                ODInfoType                    partInfo,
                ODStorageUnitView*            storageUnitView
            )
{
    SampleCode_SamplePartMethodDebug("SamplePart","WritePartInfo");

    SOM_TRY
        // Tell our frame info class to write itself out into the pre-
        // focused storage unit.
        CFrameInfo_Externalize((CFrameInfo*) partInfo, ev, storageUnitView);
        CHECK_ENV(ev);

    SOM_CATCH_ALL
    SOM_ENDTRY
}

//------------------------------------------------------------------------------
// Method:        ClonePartInfo
//
// Description:    When a frame is being cloned by the Draft, it will ask the owner
//                (part) to clone its info annotation on the frame.
//
//                The part uses a struct to encapsulate the information
//                we store with each frame, and we use a utility function to clone
//                the info to the storage unit view.
//------------------------------------------------------------------------------

SOM_Scope    void
SOMLINK        SamplePart__ClonePartInfo
            (
                SampleCode_SamplePart*        somSelf,
                Environment*                ev,
                ODDraftKey                    key,
                  ODInfoType                    partInfo,
                ODStorageUnitView*            storageUnitView,
                ODFrame*                    scopeFrame
            )
{
    SOM_Trace("SamplePart","ClonePartInfo");

    SOM_TRY
        // Tell our frame info class to write itself out into the pre-
        // focused storage unit.
        CFrameInfo_CloneInto((CFrameInfo*) partInfo, ev, key, storageUnitView, scopeFrame);
        CHECK_ENV(ev);

    SOM_CATCH_ALL
    SOM_ENDTRY
}

//==============================================================================
#pragma mark    • Layout •
//==============================================================================

//------------------------------------------------------------------------------
// Method:        DisplayFrameAdded
// Origin:        ODPart
//
// Description:    This method is called in response to a frame being created for
//                the part.
//
//                The part records the existence of a new display frame in its
//                internal display frame list, as well as, verify that the frame
//                is "set up" correctly (i.e., valid viewType). The part also
//                creates and stores its "frame info" class in the new frame.
//------------------------------------------------------------------------------

SOM_Scope    void
SOMLINK        SamplePart__DisplayFrameAdded
            (
                SampleCode_SamplePart*        somSelf,
                Environment*                ev,
                ODFrame*                    frame
            )
{
    SampleCode_SamplePartData *somThis = SampleCode_SamplePartGetData(somSelf);
    SampleCode_SamplePartMethodDebug("SamplePart","DisplayFrameAdded");

    // If we are being embedded into another part, the presentation field
    // will (most likely) be unset; we need to set it something meaningful.
    // The view field may also be null, if so, we prefer to be displayed
    // in a frame view.

    SOM_TRY

        CFrameInfo*     frameInfo;
        CFrameProxy*    proxy;

        if ( ODFrame_GetPresentation(frame, ev) != gGlobals->fMainPresentation  )
        {
            ODFrame_SetPresentation(frame, ev, gGlobals->fMainPresentation);
            CHECK_ENV(ev);
        }
        CHECK_ENV(ev);

        if ( ODFrame_GetViewType(frame, ev) == kODNullTypeToken )
        {
            ODFrame_SetViewType(frame, ev, gGlobals->fFrameView);
            CHECK_ENV(ev);
        }
        CHECK_ENV(ev);

        // Hang our "state" info off of the new display frame. We use
        // the CFrameInfo object for activation, updating, and window
        // maintenance.
        frameInfo = CFrameInfo_Create(ODGetSessionFromPart(ev,_fSelf));
        ODFrame_SetPartInfo(frame, ev, (ODInfoType)frameInfo);
        CHECK_ENV(ev);

        // If the frame being added is a root frame, we know that a window
        // is associated with this frame. Notify ourselves that we need to
        // clean it up when the frame goes away.
        if ( ODFrame_IsRoot(frame, ev) )
            CFrameInfo_SetShouldDisposeWindow(frameInfo, kODTrue);
        CHECK_ENV(ev);

        // The proxy class will refcount the frame passed to it, so we
        // don't need to worry about refcounting the display frame.
        proxy = CFrameProxy_Create();
        CFrameProxy_InitFrameProxyWithFrame(proxy, ev, frame);
        CHECK_ENV(ev);

        // Add the frame to the display frame collection.
        CLinkedList_Add(_fDisplayFrames, (ODPtr)proxy);

        // Since we maintain a persistent list of weak references to our
        // display frames, having one added to the part dirties it.
        _SetDirty(somSelf, ev);
        CHECK_ENV(ev);

    SOM_CATCH_ALL
    SOM_ENDTRY
}

//------------------------------------------------------------------------------
// Method:        DisplayFrameConnected
// Origin:        ODPart
//
// Description:    This method is called when one of our display frames, previously
//                written out, is internalized. This method is called instead of
//                DisplayFrameAdded because a "new" frame is not being created;
//                an existing one is being reconstituted.
//
//                The part first checks to see if we can match its frame to an
//                ID in the Display frame list; if so, we put the frame into the
//                proxy. For frames we do not recognize, just add them.
//------------------------------------------------------------------------------

SOM_Scope    void
SOMLINK        SamplePart__DisplayFrameConnected
            (
                SampleCode_SamplePart*        somSelf,
                Environment*                ev,
                ODFrame*                    frame
            )
{
    SampleCode_SamplePartData *somThis = SampleCode_SamplePartGetData(somSelf);
    SampleCode_SamplePartMethodDebug("SamplePart","DisplayFrameConnected");

    SOM_TRY

        CFrameProxy*    proxy = kODNULL;
        CLink*            link = kODNULL;
        ODBoolean        found = kODFalse;

        // Iterate over our display collection to match the frame with
        // an existing proxy with the correct frame ID. If we find it,
        // replace the ID with the actual frame. If we don't find it,
        // signal an error.
        for ( link = CLinkedList_First(_fDisplayFrames);
             CLink_Content(link);
             link = CLink_Next(link) )
        {
            // Get the ID of the frame we are going to weakly reference.
            proxy = (CFrameProxy*) CLink_Content(link);

            if ( CFrameProxy_GetID(proxy) == ODFrame_GetID(frame, ev) )
            {
                // The proxy class will refcount the frame passed to it, so we
                // don't need to worry about refcounting the display frame.
                CFrameProxy_SetFrame(proxy, ev,frame);
                CHECK_ENV(ev);

                found = kODTrue;
            }
            CHECK_ENV(ev);
        }

        // Parts typically operate under the assumption that they have previous
        // knowledge of a frame before it is connected to it. This knowledge
        // should come from having read in the frame reference when the part
        // was internalized. If the frame is an "unknown", the part was probably
        // bound to another editors storage unit because the editor is missing or
        // the user changed the editor in the Info dialog.
        if ( found )
        {
            // If a display frame is connected to us with an unrecognizable
            // presentation, we need to set it to something meaningful.

            if ( ODFrame_GetPresentation(frame, ev) != gGlobals->fMainPresentation )
            {
                ODFrame_SetPresentation(frame, ev, gGlobals->fMainPresentation);
                CHECK_ENV(ev);
            }
            CHECK_ENV(ev);

            if ( ODFrame_IsRoot(frame, ev) )
            {
                // If the frame being added is a root frame, we know that a window
                // is associated with this frame. Notify ourselves that we need to
                // clean it up when the frame goes away.
                CFrameInfo* frameInfo = (CFrameInfo*) ODFrame_GetPartInfo(frame, ev);
                CHECK_ENV(ev);

                CFrameInfo_SetShouldDisposeWindow(frameInfo, kODTrue);

                // In addition, we need to verify that the frame is in "frame" view.
                // If the user dragged an icon from a document to Finder and then
                // opens the resultant document, the view would be "icon". However
                // displaying a icon is useless, so we need to change the view to
                // frame.
                if (  ODFrame_GetViewType(frame, ev) != gGlobals->fFrameView )
                    ODFrame_SetViewType(frame, ev, gGlobals->fFrameView);
                CHECK_ENV(ev);
            }
        }
        else
        {
            // If an unrecognizable frame is connected to us, treat it like a "new"
            // frame and call our method to add it.
            _DisplayFrameAdded(somSelf, ev, frame);
        }

    SOM_CATCH_ALL
    SOM_ENDTRY
}

//------------------------------------------------------------------------------
// Method:        DisplayFrameRemoved
// Origin:        ODPart
//
// Description:    This method is called in response to a frame being removed from
//                the part.
//
//                The part removes the frame from its internal display frame list
//                and reliquishes any foci that it still owned. Lastly, if the
//                frame has a source frame (it was the root frame of a part
//                window), we will record the part window bounds so that any
//                subsequent part windows opened on the source frame will appear
//                in the same location.
//------------------------------------------------------------------------------

SOM_Scope    void
SOMLINK        SamplePart__DisplayFrameRemoved
            (
                SampleCode_SamplePart*        somSelf,
                Environment*                ev,
                ODFrame*                    frame
            )
{
    SampleCode_SamplePartData *somThis = SampleCode_SamplePartGetData(somSelf);
    SampleCode_SamplePartMethodDebug("SamplePart","DisplayFrameRemoved");

    SOM_TRY

        CLink*            link;
        CFrameInfo*        frameInfo;
        CFrameProxy*    proxy;

        frameInfo = (CFrameInfo*) ODFrame_GetPartInfo(frame, ev);
        CHECK_ENV(ev);

        // Make sure the frame going away does not own any foci. Forgetting
        // to do this, will cause a "refcounting" error when the frame
        // is deleted by the draft.
        _RelinquishAllFoci(somSelf, ev, frame);
        CHECK_ENV(ev);

        // If removing a child window, show zoom rects back to source.
        // NOTE: This has to be done before CleanupDisplayFrame because
        // CleanupDisplayFrame will remove the relationship.
        if ( ODFrame_IsRoot(frame, ev) && CFrameInfo_HasSourceFrame(frameInfo) )
        {
            ODWindow* window = ODFrame_AcquireWindow(frame, ev);
            _ZoomPartWindow(somSelf, ev, CFrameInfo_GetSourceFrame(frameInfo, ev),
                                    window, kWindowClosing);
        }

        // Clean up the display frame.
        _CleanupDisplayFrame(somSelf, ev, frame, kFrameRemoved);
        CHECK_ENV(ev);
        // Clean up any associated window.
        _CleanupWindow(somSelf, ev, frame);
        CHECK_ENV(ev);
        // Dispose of the frame's runtime state info.
        ODFrame_SetPartInfo(frame, ev, (ODInfoType) kODNULL);
        CFrameInfo_Delete(&frameInfo, ev);
        CHECK_ENV(ev);

        // Remove the display frame from our collection.
        for ( link = CLinkedList_First(_fDisplayFrames);
             CLink_Content(link);
             link = CLink_Next(link) )
        {
            proxy = (CFrameProxy*) CLink_Content(link);

            if ( ODObjectsAreEqual(ev, CFrameProxy_GetFrame(proxy,ev), frame) )
            {
                // Delete the proxy object and it's contents. The frame's
                // refcount will be decremented in the proxy destructor.
                link = link->prev;
                CLinkedList_Remove(_fDisplayFrames, proxy);
                CFrameProxy_Delete(&proxy, ev);
            }
            CHECK_ENV(ev);
        }

        // Since we maintain a persistent list of weak references to our
        // display frames, having one removed from the part dirties it.
        _SetDirty(somSelf, ev);
        CHECK_ENV(ev);

    SOM_CATCH_ALL
        // Alert the user of the problem.
        _DoDialogBox(somSelf, ev, frame, kErrorBoxID, kErrRemoveFrame);
        // Change the exception value, so the DocShell doesn't display an
        // error dialog.
        ODSetSOMException(ev, kODErrAlreadyNotified, kODNULL);
    SOM_ENDTRY
}

//------------------------------------------------------------------------------
// Method:        DisplayFrameClosed
//
// Description:    This method is called in response to a frame being closed as a
//                result of the document having been closed by the user.
//
//                The part behaves much the same way that it would if a frame were
//                removed (see above), except that we don't need to cache runtime
//                information.
//------------------------------------------------------------------------------

SOM_Scope    void
SOMLINK        SamplePart__DisplayFrameClosed
            (
                SampleCode_SamplePart*        somSelf,
                Environment*                ev,
                ODFrame*                    frame
            )
{
    SampleCode_SamplePartData *somThis = SampleCode_SamplePartGetData(somSelf);
    SampleCode_SamplePartMethodDebug("SamplePart","DisplayFrameClosed");

    SOM_TRY

        CLink*            link = kODNULL;
        CFrameInfo*        frameInfo = kODNULL;
        CFrameProxy*    proxy = kODNULL;

        frameInfo = (CFrameInfo*) ODFrame_GetPartInfo(frame, ev);
        CHECK_ENV(ev);

        // Make sure the frame going away does not own any foci. Forgetting
        // to do this, will cause a "refcounting" error when the frame
        // is deleted by the draft.
        _RelinquishAllFoci(somSelf, ev, frame);
        CHECK_ENV(ev);

        // Clean up the display frame.
        _CleanupDisplayFrame(somSelf, ev, frame, kFrameRemoved);
        CHECK_ENV(ev);
        // Clean up any associated window.
        _CleanupWindow(somSelf, ev, frame);
        CHECK_ENV(ev);
        // Dispose of the frame's runtime state info.
        ODFrame_SetPartInfo(frame, ev, (ODInfoType) kODNULL);
        CHECK_ENV(ev);
        CFrameInfo_Delete(&frameInfo, ev);

        // Remove the display frame from our collection.
        for ( link = CLinkedList_First(_fDisplayFrames);
             CLink_Content(link);
             link = CLink_Next(link) )
        {
            // Get the ID of the frame we are going to weakly reference.
            proxy = (CFrameProxy*) CLink_Content(link);

            if ( CFrameProxy_GetID(proxy) == ODFrame_GetID(frame, ev) )
            {
                // Release the frame reference, but don't get rid of the
                // proxy object because "closed" frames may be reconnected
                // before the document is closed.
                CFrameProxy_Purge(proxy, ev);
            }
            CHECK_ENV(ev);
        }

    SOM_CATCH_ALL
        // Alert the user of the problem.
        _DoDialogBox(somSelf, ev, frame, kErrorBoxID, kErrRemoveFrame);
        // Change the exception value, so the DocShell doesn't display an
        // error dialog.
        ODSetSOMException(ev, kODErrAlreadyNotified, kODNULL);
    SOM_ENDTRY
}

//------------------------------------------------------------------------------
// Method:        CleanupDisplayFrame
// Origin:        SamplePart
//
// Description:    This method is called when a frame has been closed or removed.
//                The method cleans up the references and state information stored
//                in the CFrameInfo class.
//------------------------------------------------------------------------------

SOM_Scope    void
SOMLINK        SamplePart__CleanupDisplayFrame
            (
                SampleCode_SamplePart*    somSelf,
                Environment*            ev,
                ODFrame*                frame,
                ODBoolean                frameRemoved
            )
{
    SampleCode_SamplePartData *somThis = SampleCode_SamplePartGetData(somSelf);
    SampleCode_SamplePartMethodDebug("SamplePart","CleanupDisplayFrame");

    SOM_TRY
        ODFrame*     sourceFrame = kODNULL;
        CFrameInfo* sourceFrameInfo = kODNULL;
        CFrameInfo*    frameInfo = kODNULL;
        ODError        error = noErr;

        frameInfo = (CFrameInfo*) ODFrame_GetPartInfo(frame, ev);
        CHECK_ENV(ev);

        TRY
            // If we are the root of a child window, we need to notify
            // our source frame that we are going away.
            if ( CFrameInfo_HasSourceFrame(frameInfo) )
            {
                sourceFrame = CFrameInfo_GetSourceFrame(frameInfo, ev);
                CHECK_ENV(ev);
                sourceFrameInfo = (CFrameInfo*) ODFrame_GetPartInfo(sourceFrame, ev);
                CHECK_ENV(ev);

                if ( frameRemoved )
                {
                    // Invalidate the source frame. We do this because the
                    // source frame may have a unique display when it has
                    // been opened into a part window. This forces the
                    // frame to redraw "not opened".
                    ODFrame_Invalidate(sourceFrame, ev, kODNULL, kODNULL);
                    CHECK_ENV(ev);
                }

                // Tell the source frame that its dependent is going away.
                CFrameInfo_ReleaseDependentFrame(sourceFrameInfo, ev);

                // Release our reference to the source frame.
                CFrameInfo_ReleaseSourceFrame(frameInfo, ev);

                // If the frame is the root, it is a part window going away
                // and we need to notify our source frame that it no longer
                // has a part window.
                if ( ODFrame_IsRoot(frame, ev) )
                    CFrameInfo_SetPartWindow(sourceFrameInfo, ev, kODNULL);
            }
        CATCH_ALL
            error = ErrorCode();
        ENDTRY

        TRY
            // If the frame was removed from the document, we need to remove
            // any child window displaying that frame.
            if ( frameRemoved )
            {
                // If we have a child window, we need to close it.
                ODWindow* window = CFrameInfo_AcquirePartWindow(frameInfo, ev);

                if ( window )
                {
                    CFrameInfo_SetPartWindow(frameInfo, ev, kODNULL);
                    ODWindow_CloseAndRemove(window, ev);
                }
            }
        CATCH_ALL
            error = ErrorCode();
        ENDTRY

        TRY
            // If we have dependent frames, we need to notify them that we
            // are going away.

            if ( CFrameInfo_HasDependentFrame(frameInfo) )
            {
                CFrameInfo* dependentFrameInfo = kODNULL;
                // Get the frame that is dependent on this one. We can safely
                // do this because we only reference our own display frames.
                ODFrame* dependentFrame =  CFrameInfo_GetDependentFrame(frameInfo, ev);
                CHECK_ENV(ev);
                dependentFrameInfo = (CFrameInfo*)ODFrame_GetPartInfo(dependentFrame, ev);
                CHECK_ENV(ev);

                // Tell the dependent frame that its source is going away.
                CFrameInfo_ReleaseSourceFrame(dependentFrameInfo, ev);

                // Release our reference to the dependent frame.
                CFrameInfo_ReleaseDependentFrame(frameInfo, ev);
            }
        CATCH_ALL
            error = ErrorCode();
        ENDTRY

        // If anything went wrong, signal an error.
        THROW_IF_ERROR(error);

    SOM_CATCH_ALL
    SOM_ENDTRY
}

//------------------------------------------------------------------------------
// Method:        AttachSourceFrame
// Origin:        ODPart
//
// Description:    If the part which we are contained in is opened into a part
//                window, it is required to iterate over its embedded frames and
//                add new display frames in the part window. After each new
//                embedded frame is created, this method will be called.
//
//                Given all that, and given our lack of interesting
//                content, we just validate the frame and attach it to its source.
//------------------------------------------------------------------------------

SOM_Scope    void
SOMLINK        SamplePart__AttachSourceFrame
            (
                SampleCode_SamplePart*        somSelf,
                Environment*                ev,
                ODFrame*                    frame,
                ODFrame*                    sourceFrame
            )
{
    SampleCode_SamplePartMethodDebug("SamplePart","AttachSourceFrame");

    SOM_TRY

        CFrameInfo* frameInfo = kODNULL;

        // Tell the new frame about its source.
        frameInfo = (CFrameInfo*) ODFrame_GetPartInfo(frame, ev);
        CHECK_ENV(ev);
        CFrameInfo_SetSourceFrame(frameInfo, ev, sourceFrame);
        CHECK_ENV(ev);

        // And tell the source about its new dependent.
        frameInfo = (CFrameInfo*) ODFrame_GetPartInfo(sourceFrame, ev);
        CHECK_ENV(ev);
        CFrameInfo_SetDependentFrame(frameInfo, ev, frame);
        CHECK_ENV(ev);

        // In both cases, refcounting of the frame and sourceFrame is
        // handled by the CFrameInfo class.

    SOM_CATCH_ALL
    SOM_ENDTRY
}

//------------------------------------------------------------------------------
// Method:        ViewTypeChanged
// Origin:        ODPart
//
// Description:    This method is called in response to one of our display frame's
//                viewType field being modified. We call this method on ourselves
//                when new display frames are added, but it call also be called
//                when the user changes the view in the "part info" dialog.
//
//                The part first loads the appropriate view icons if needed and
//                then calculates a new "used" shape based on the bounds of the
//                new view type. If any problems occur while changing the view,
//                the part defaults back to frame view (the part's default view).
//------------------------------------------------------------------------------

SOM_Scope    void
SOMLINK        SamplePart__ViewTypeChanged
            (
                SampleCode_SamplePart*        somSelf,
                Environment*                ev,
                ODFrame*                    frame
            )
{
    SampleCode_SamplePartMethodDebug("SamplePart","ViewTypeChanged");

    SOM_TRY

        ODShape* newUsedShape = kODNULL;    ODVolatile(newUsedShape);

        TRY
            // Change this frame's used shape to match the new view setting.
            newUsedShape = _CalcNewUsedShape(somSelf, ev, frame);
            CHECK_ENV(ev);
        CATCH_ALL
            ODSafeReleaseObject(newUsedShape);
            RERAISE;
        ENDTRY

        ODFrame_Invalidate(frame, ev, kODNULL, kODNULL);
        CHECK_ENV(ev);
        ODFrame_ChangeUsedShape(frame, ev, newUsedShape, kODNULL);
        CHECK_ENV(ev);
        ODFrame_Invalidate(frame, ev, kODNULL, kODNULL);
        CHECK_ENV(ev);

        ODReleaseObject(ev, newUsedShape);

    SOM_CATCH_ALL
    SOM_ENDTRY
}

//------------------------------------------------------------------------------
// Method:        CalcNewUsedShape
// Origin:        SamplePart
//
// Description:    This method is called in response to one of display frame's view
//                being changed. The method calculates the appropriate usedShape
//                for the new view type.
//------------------------------------------------------------------------------

SOM_Scope    ODShape*
SOMLINK        SamplePart__CalcNewUsedShape
             (
                SampleCode_SamplePart*        somSelf,
                Environment*                ev,
                ODFrame*                    frame
            )
{
    ODShape* usedShape = kODNULL;
    ODVolatile(usedShape);

    SampleCode_SamplePartMethodDebug("SamplePart","CalcNewUsedShape");

    SOM_TRY

        RgnHandle     usedRgn;
        ODTypeToken view;

        ODVolatile(usedRgn);

        view = ODFrame_GetViewType(frame, ev);
        CHECK_ENV(ev);

        // If the view is "frame", we intentionally return a nil shape;
        // doing so, will reset the used shape to equal the frame shape.

        if ( view == gGlobals->fLargeIconView ||
                view == gGlobals->fSmallIconView ||
                view == gGlobals->fThumbnailView )
        {
            TRY
                Rect        bounds;
                usedRgn = ODNewRgn();

                if ( view == gGlobals->fLargeIconView || view == gGlobals->fSmallIconView )
                {
                    OSErr    result = noErr;
                    ODSLong    res = BeginUsingLibraryResources();

                    // Set the bounds rect for the icon size.
                    SetRect(&bounds, 0, 0,
                        (view == gGlobals->fLargeIconView) ? kODLargeIconSize : kODSmallIconSize,
                        (view == gGlobals->fLargeIconView) ? kODLargeIconSize : kODSmallIconSize);

                    // Convert the icon mask into a Region.
                    result = IconIDToRgn(usedRgn,&bounds,atAbsoluteCenter, kBaseResourceID);
                    EndUsingLibraryResources(res);

                    THROW_IF_ERROR(result);
                }
                else if ( view == gGlobals->fThumbnailView )
                {
                    PicHandle thumbnail = _GenerateThumbnail(somSelf, ev, frame);

                    if ( thumbnail )
                        bounds = (**thumbnail).picFrame;
                    else
                        SetRect(&bounds, 0, 0, kODThumbnailSize, kODThumbnailSize);

                    RectRgn(usedRgn,&bounds);
                }

                usedShape = ODFrame_CreateShape(frame, ev);
                ODShape_SetQDRegion(usedShape, ev, usedRgn);

            CATCH_ALL
                ODSafeReleaseObject(usedShape);
                ODDisposeHandle((ODHandle)usedRgn);
                usedShape = kODNULL;
            ENDTRY
        }
    SOM_CATCH_ALL
    SOM_ENDTRY

    return usedShape;
}

//------------------------------------------------------------------------------
// Method:        UpdateFrame
// Origin:        SamplePart
//
// Description:    This method is called in response to one of our
//------------------------------------------------------------------------------

SOM_Scope    void
SOMLINK        SamplePart__UpdateFrame
             (
                SampleCode_SamplePart*        somSelf,
                Environment*                ev,
                ODFrame*                    frame,
                ODTypeToken                    view,
                ODShape*                    usedShape
            )
{
    SampleCode_SamplePartMethodDebug("SamplePart","UpdateFrame");

    SOM_TRY

        // Update the frame to have the new view and UsedShape.
        ODFrame_Invalidate(frame, ev, kODNULL, kODNULL);
        CHECK_ENV(ev);
        ODFrame_SetViewType(frame, ev, view);
        CHECK_ENV(ev);
        ODFrame_ChangeUsedShape(frame, ev, usedShape, kODNULL);
        CHECK_ENV(ev);
        ODFrame_Invalidate(frame, ev, kODNULL, kODNULL);
        CHECK_ENV(ev);

    SOM_CATCH_ALL
        // Failing isn't great, but we can live with it, so don't set ev.
        ODSetSOMException(ev, noErr, kODNULL);
    SOM_ENDTRY
}

//------------------------------------------------------------------------------
// Method:        FrameShapeChanged
// Origin:        ODPart
//
// Description:    This method is called in response to a frame's shape being
//                altered, either by the user or the part we are embedded in.
//
//                To keep all attached frames in sync, we need to propogate the
//                new frame shape the frames dependent on the changed frame. This
//                is done by observing the display frames stored in the frame info
//                and calling RequestFrameShape for each.
//------------------------------------------------------------------------------

SOM_Scope    void
SOMLINK        SamplePart__FrameShapeChanged
            (
                SampleCode_SamplePart*        somSelf,
                Environment*                ev,
                ODFrame*                    frame
            )
{
    SampleCode_SamplePartData *somThis = SampleCode_SamplePartGetData(somSelf);
    SampleCode_SamplePartMethodDebug("SamplePart","FrameShapeChanged");

    SOM_TRY
        // Adjust the "used" shape for the new frame shape.
        ODShape* usedShape = _CalcNewUsedShape(somSelf, ev, frame);
        ODFrame_ChangeUsedShape(frame, ev, usedShape, kODNULL);
        ODReleaseObject(ev, usedShape);
        CHECK_ENV(ev);
    SOM_CATCH_ALL
    SOM_ENDTRY
}

//------------------------------------------------------------------------------
// Method:        Open
// Origin:        ODPart
//
// Description:    This method is called when OpenDoc, a containing part, or the
//                active editor would like to open a frame into a seperate window.
//                If a source frame is passed into this method, the editor is
//                being asked one of two things. If the frame is the root, we are
//                being asked to open an existing document. If the frame is not
//                the root, we are being asked to open a part window. If a source
//                frame is not specified, the editor is being asked to open a new
//                window.
//------------------------------------------------------------------------------

SOM_Scope    ODID
SOMLINK        SamplePart__Open
            (
                SampleCode_SamplePart*        somSelf,
                Environment*                ev,
                ODFrame*                    frame
            )
{
    ODID windowID = kODNULLID;

    SampleCode_SamplePartData *somThis = SampleCode_SamplePartGetData(somSelf);
    SampleCode_SamplePartMethodDebug("SamplePart","Open");

    SOM_TRY

        ODWindow*             window = kODNULL;
        WindowProperties*    windowProperties = kODNULL;
        CFrameInfo*         frameInfo = kODNULL;

        ODVolatile(window);
        ODVolatile(windowProperties);

        TRY
            // Because the frame parameter being passed to us can be one of
            // three things, we must determine what it is; either the root
            // frame of a existing document, the source frame for a part
            // window, or null if we are opening a new document.

            if ( frame == kODNULL )
            {
                // Calculate the bounding rectangle for a new window
                Rect windowRect = _CalcPartWindowSize(somSelf, ev, kODNULL);
                CHECK_ENV(ev);
                // Get the default setting for a document window.
                windowProperties = _GetDefaultWindowProperties(somSelf, ev, kODNULL, &windowRect);
                CHECK_ENV(ev);
                // Create a Mac Window and register it with OpenDoc.
                window = _CreateWindow(somSelf, ev, kODNULL, kODFrameObject, windowProperties);
                CHECK_ENV(ev);
            }
            else if ( ODFrame_IsRoot(frame, ev) )
            {
                // Get the previously saved settings for the document window.
                windowProperties = _GetSavedWindowProperties(somSelf, ev, frame);
                CHECK_ENV(ev);

                if ( windowProperties == kODNULL )
                {
                    // Calculate the bounding rectangle for a new window
                    Rect windowRect = _CalcPartWindowSize(somSelf, ev, frame);
                    CHECK_ENV(ev);
                    // Get the default setting for a document window.
                    windowProperties = _GetDefaultWindowProperties(somSelf, ev, kODNULL, &windowRect);
                    CHECK_ENV(ev);
                }

                // Create a Mac Window and register it with OpenDoc.
                window = _CreateWindow(somSelf, ev, frame, kODFrameObject, windowProperties);
                CHECK_ENV(ev);

                // We release the source frame here because we didn't call
                // EndGetWindowProperties and becuase we are done with it.
                ODReleaseObject(ev, windowProperties->sourceFrame);
            }
            else // frame is a source frame
            {
                window = _AcquireFramesWindow(somSelf, ev, frame);
                CHECK_ENV(ev);

                if ( window == kODNULL )
                {
                    // Calculate the bounding rectangle for a new window
                    Rect windowRect = _CalcPartWindowSize(somSelf, ev, frame);
                    CHECK_ENV(ev);
                    // Get the default setting for a document window.
                    windowProperties = _GetDefaultWindowProperties(somSelf, ev, frame, &windowRect);
                    CHECK_ENV(ev);
                    // Create a Mac Window and register it with OpenDoc.
                    window = _CreateWindow(somSelf, ev, frame, kODFrameObject, windowProperties);
                    CHECK_ENV(ev);

                    // Tell the source frame that it is opened in a part window.
                    frameInfo = (CFrameInfo*) ODFrame_GetPartInfo(frame, ev);
                    CFrameInfo_SetPartWindow(frameInfo, ev, window);

                    _ZoomPartWindow(somSelf, ev, frame, window, kWindowOpening);
                }
            }
            CHECK_ENV(ev);

            // Cleanup allocate memory.
            ODDisposePtr(windowProperties);

        CATCH_ALL
            // If we threw early, the source frame's refcount may be too high.
            if ( windowProperties )
                ODSafeReleaseObject(windowProperties->sourceFrame);
            // Cleanup the created items.
            ODDisposePtr(windowProperties);
            RERAISE;
        ENDTRY

        TRY
            // Create the window's root facet.
            ODWindow_Open(window, ev);
            CHECK_ENV(ev);
            // Make the window visible.
            ODWindow_Show(window, ev);
            CHECK_ENV(ev);
            // Activate and select the window.
            ODWindow_Select(window, ev);
            CHECK_ENV(ev);

            // Get window id to return.
            windowID = (window ? ODWindow_GetID(window, ev) : kODNULLID);
            ODReleaseObject(ev, window);

        CATCH_ALL
            ODSafeReleaseObject(window);
            RERAISE;
        ENDTRY

    SOM_CATCH_ALL
        windowID = kODNULLID;
    SOM_ENDTRY

    return (windowID);
}

//------------------------------------------------------------------------------
// Method:        AcquireFramesWindow
// Origin:        SamplePart
//
// Description:    This method is called by the part when a frame, that has been
//                previously opened, is being opened again.
//
//                The method retrieves the existing window for the frame and
//                returns it.
//------------------------------------------------------------------------------

SOM_Scope    ODWindow*
SOMLINK        SamplePart__AcquireFramesWindow
            (
                SampleCode_SamplePart*        somSelf,
                Environment*                ev,
                ODFrame*                    frame
            )
{
    CFrameInfo* frameInfo = kODNULL;
    ODWindow*     window = kODNULL;

    SampleCode_SamplePartMethodDebug("SamplePart","AcquireFramesWindow");

    frameInfo = (CFrameInfo*) ODFrame_GetPartInfo(frame, ev);
    CHECK_ENV(ev);
    window = CFrameInfo_AcquirePartWindow(frameInfo, ev);
    CHECK_ENV(ev);

    return window;
}

//-------------------------------------------------------------------------------
// Method:        CreateWindow
// Origin:        SamplePart
//
// Description:    This method is called by the part when a window needs to be
//                created for a frame being opened.
//
//                The part uses the information passed in windowProperties to
//                create the appropriate window. The generated window is
//                registered with OpenDoc as a new window (RegisterWindow) or as a
//                window from an existing document (RegisterWindowForFrame).
//------------------------------------------------------------------------------

SOM_Scope    ODWindow*
SOMLINK        SamplePart__CreateWindow
             (
                SampleCode_SamplePart*        somSelf,
                Environment*                ev,
                ODFrame*                    frame,
                ODType                        frameType,
                WindowProperties*            windowProperties
            )
{
    ODWindow* window = kODNULL;

    SampleCode_SamplePartData *somThis = SampleCode_SamplePartGetData(somSelf);
    SampleCode_SamplePartMethodDebug("SamplePart","CreateWindow");

    SOM_TRY

        ODPlatformWindow    platformWindow    = kODNULL;
        ODSShort            errMsgNum        = noErr;
        ODSession*             session         = kODNULL;
        ODWindowState*        windowState     = kODNULL;
        ODBoolean             saveWindow        = kODFalse;
        ODBoolean             shouldDispose    = kODFalse;

        // Using the name and the calculated rectangle, create a new window.
        // Note that we are allocating the window record in temp mem using
        // the OpenDoc memory mgr. This helps reduce app heap usage.
        // In addition, OpenDoc requires that all new windows be initially hidden
        // so that it can correctly layer windows/palettes.
        platformWindow = NewCWindow((Ptr)ODNewPtr(sizeof(WindowRecord), kODNULL),
                                    &(windowProperties->boundsRect),
                                    windowProperties->title,
                                    kODFalse, /* visible */
                                    windowProperties->procID,
                                    (WindowPtr)-1L,
                                    windowProperties->hasCloseBox,
                                    windowProperties->refCon);

        TRY
            if ( platformWindow )
            {
                session = ODGetSessionFromPart(ev,_fSelf);
                CHECK_ENV(ev);
                windowState = ODSession_GetWindowState(session, ev);
                CHECK_ENV(ev);

                // Shoud the window be saved in the document? Yes if the root frame is
                // persistent.
                saveWindow = (ODISOStrCompare(frameType, kODFrameObject) == 0);

                // Tell the window object that we will be disposing the window record
                // when the root frame is closed/removed.
                shouldDispose = kODFalse;

                // Determine whether we are creating a new window (frame is null),
                // or opening a previous saved window (frame is valid).

                if ( frame == kODNULL )
                {
                    // Tell OpenDoc about it by creating an OpenDoc window object.
                    window = ODWindowState_RegisterWindow(
                                    windowState, ev,
                                    platformWindow,                    // Macintosh WindowPtr
                                    frameType,                        // Frame type (Persistent/Non-persistent)
                                    windowProperties->isRootWindow,    // Is this a document window?
                                    windowProperties->isResizable,    // Is this window resizeable?
                                    windowProperties->isFloating,    // Is this window floating?
                                    saveWindow,                        // Should this window be persistent?
                                    shouldDispose,                    // (see comment above)
                                    _fSelf,                            // Part reference to us
                                    gGlobals->fFrameView,                        // What view should the window have?
                                    gGlobals->fMainPresentation,                // What presentation should the window have?
                                    windowProperties->sourceFrame);    // The display frame being opened, if any
                    CHECK_ENV(ev);
                }
                else
                {
                    // Tell OpenDoc about it by creating an OpenDoc window object.
                    window = ODWindowState_RegisterWindowForFrame(
                                    windowState, ev,
                                    platformWindow,                    // Macintosh WindowPtr
                                    frame,                             // root frame for window
                                    windowProperties->isRootWindow,    // Is this a document window?
                                    windowProperties->isResizable,    // Is this window resizeable?
                                    windowProperties->isFloating,    // Is this window floating?
                                    saveWindow,                        // Should this window be persistent?
                                    shouldDispose,                    // (see comment above)
                                    windowProperties->sourceFrame);    // The display frame being opened, if any
                    CHECK_ENV(ev);
                }
            }

        CATCH_ALL
            // Cleanup Macintosh Window.
            CloseWindow(platformWindow);
            ODDisposePtr(platformWindow);
            // Get the right error message for the problem.
            errMsgNum = (!frame && windowProperties->sourceFrame)
                                    ? kErrCantOpenPartWindow : kErrCantOpenDocWindow;
            SetErrorCode(errMsgNum);
            RERAISE;
        ENDTRY

    SOM_CATCH_ALL
        // Alert the user of the problem.
        _DoDialogBox(somSelf, ev, frame, kErrorBoxID, ErrorCode());
        // Change the exception value, so the DocShell doesn't display an
        // error dialog.
        ODSetSOMException(ev, kODErrAlreadyNotified, kODNULL);
    SOM_ENDTRY

    return window;
}

//------------------------------------------------------------------------------
// Method:        CleanupWindow
// Origin:        SamplePart
//
// Description:    This method is called by the part when a window needs to be
//                cleaned up for a frame being closed/removed.
//
//                The part deallocates the window buffer allocated in the
//                CreateWindow() method.
//------------------------------------------------------------------------------

SOM_Scope    void
SOMLINK        SamplePart__CleanupWindow
            (
                SampleCode_SamplePart*        somSelf,
                Environment*                ev,
                ODFrame*                    frame
            )
{
       ODWindow* window = kODNULL;

    SampleCode_SamplePartData *somThis = SampleCode_SamplePartGetData(somSelf);
    SampleCode_SamplePartMethodDebug("SamplePart","CleanupWindow");

    ODVolatile(window);

       TRY
        CFrameInfo*    frameInfo = (CFrameInfo*) ODFrame_GetPartInfo(frame, ev);
        CHECK_ENV(ev);
        if ( CFrameInfo_ShouldDisposeWindow(frameInfo) )
        {
            ODPlatformWindow windowPtr = kODNULL;

            window = ODFrame_AcquireWindow(frame, ev);
            CHECK_ENV(ev);
            THROW_IF_NULL(window);

            windowPtr = ODWindow_GetPlatformWindow(window, ev);
            CHECK_ENV(ev);
            CloseWindow(windowPtr);
            ODDisposePtr(windowPtr);
            ODReleaseObject(ev, window);
        }
    CATCH_ALL
        _DoDialogBox(somSelf, ev, frame, kErrorBoxID, kErrWindowGone);
        ODSafeReleaseObject(window);
        // consume excpetion because it's not fatal.
    ENDTRY

}

//------------------------------------------------------------------------------
// Method:        GetDefaultWindowProperties
// Origin:        SamplePart
//
// Description:    This method is called by the part when a new window is being
//                created. The method examines the frame which is being opened
//                a generates the default window parameters to pass to the
//                Mac Toolbox.
//------------------------------------------------------------------------------

SOM_Scope WindowProperties*
SOMLINK SamplePart__GetDefaultWindowProperties
        (
            SampleCode_SamplePart *somSelf,
            Environment *ev,
            ODFrame* sourceFrame,
            Rect* windowRect
        )
{
    WindowProperties* windowProperties = kODNULL;

    SampleCode_SamplePartData *somThis = SampleCode_SamplePartGetData(somSelf);
    SampleCode_SamplePartMethodDebug("SamplePart","GetDefaultWindowProperties");

    ODVolatile( windowProperties );

    SOM_TRY
        ODIText* windowName;

        windowProperties = (WindowProperties*) ODNewPtr(sizeof(WindowProperties), kODNULL);

        // Calculate the offset for the window based on the sourceFrame.
        if ( sourceFrame )
            (void)_CalcPartWindowPosition(somSelf, ev, sourceFrame, windowRect);
        else
            OffsetRect(windowRect, kALittleNudge,
                        GetMBarHeight() + kMacWindowTitleBarHeight);
        CHECK_ENV(ev);

        // Set the window bounds based on the calculated rect.
        windowProperties->boundsRect = *windowRect;

        // Get the part name to use for the new window.
        windowName = GetPartName( ev, _fSelf, kSamplePartCategory);

        // Convert the ODIText into a Pascal string.
        if (windowName)
        {
            GetITextPString(windowName, windowProperties->title);
            DisposeIText(windowName);
        }

        // Fill in the other fields of the Window Properties struct.

        windowProperties->procID = zoomDocProc;
        windowProperties->hasCloseBox = kODTrue;
        windowProperties->refCon = (long) kODNULL;
        windowProperties->wasVisible = kODFalse;
        windowProperties->isResizable = kODTrue;
        windowProperties->isFloating = kODFalse;
        windowProperties->isRootWindow = sourceFrame ? kODFalse : kODTrue;
        windowProperties->shouldShowLinks = kODFalse;
        windowProperties->sourceFrame = sourceFrame;

    SOM_CATCH_ALL
        ODDisposePtr(windowProperties);
    SOM_ENDTRY

    return windowProperties;
}

//------------------------------------------------------------------------------
// Method:        GetSavedWindowProperties
// Origin:        SamplePart
//
// Description:    This method is called by the part to read in saved information
//                for a window from an existing document.
//------------------------------------------------------------------------------

SOM_Scope    WindowProperties*
SOMLINK        SamplePart__GetSavedWindowProperties
             (
                SampleCode_SamplePart*        somSelf,
                Environment*                ev,
                ODFrame*                    frame
            )
{
    WindowProperties*    windowProperties = kODNULL;

    SampleCode_SamplePartData *somThis = SampleCode_SamplePartGetData(somSelf);
    SampleCode_SamplePartMethodDebug("SamplePart","GetSavedWindowProperties");

    ODVolatile( windowProperties );

    SOM_TRY

        windowProperties = (WindowProperties*) ODNewPtr(sizeof(WindowProperties), kODNULL);

        // If we fail to load the window properties from storage, delete
        // the structure so the calling code will behave appropriately.
        if ( BeginGetWindowProperties(ev, frame, windowProperties) )
        {
            ODIText*    windowName;
            RgnHandle     windowRgn;
            ODBoolean     repositionWindow;
            Rect         adjustedBounds;

            // Note: We don't call EndGetWindowProperties because it releases the
            // source frame, which we will need after this method returns.

            // Get the part's name to use for the new window.
            windowName = GetPartName(ev, _fSelf, kSamplePartCategory);
            // Convert the ODIText into a Pascal string.
            GetITextPString(windowName, windowProperties->title);
            DisposeIText( windowName );

            // Verify the window is still visible on a monitor.

            windowRgn = ODNewRgn();
            repositionWindow = kODFalse;

            // We are only concerned with the window's title bar being
            // visible, so calcuate the titlebar rect from the current
            // window bounds.
            adjustedBounds = windowProperties->boundsRect;
            adjustedBounds.bottom = adjustedBounds.top;
            adjustedBounds.top -= kMacWindowTitleBarHeight;

            // Intersect the monitor's region
            RectRgn(windowRgn, &adjustedBounds);
            SectRgn(windowRgn, GetGrayRgn(), windowRgn);

            if ( !EmptyRgn(windowRgn) )
            {
                // If the visible portion of the window is too small, we need
                // to reposition it.
                Rect intersectedBounds = (**windowRgn).rgnBBox;
                if ( (intersectedBounds.right-intersectedBounds.left < kMinHorzVisPortion) ||
                        (intersectedBounds.bottom-intersectedBounds.top < kMinVertVisPortion) )
                    repositionWindow = kODTrue;
            }
            else
            {
                // If the window is completely offscreen, we need to reposition it.
                repositionWindow = kODTrue;
            }
            ODDisposeHandle((ODHandle)windowRgn);

            // If not, we need to move it so the user can see it.
            if ( repositionWindow )
            {
                Rect windowRect = (windowProperties->boundsRect);
                // Move the window to {0,0} coordinates.
                OffsetRect(&windowRect, -windowRect.left, -windowRect.top);
                // Now move the window to the default window position.
                OffsetRect(&windowRect, kALittleNudge, GetMBarHeight() + kMacWindowTitleBarHeight);
                // Save the new window position in our windowProperties.
                windowProperties->boundsRect = windowRect;
            }
        }
        else
        {
            // If we were unable to re-load window properties, dispose of the
            // struct.
            ODDisposePtr(windowProperties);
        }
        CHECK_ENV(ev);

    SOM_CATCH_ALL
        ODDisposePtr( windowProperties );
    SOM_ENDTRY

    return windowProperties;
}

//------------------------------------------------------------------------------
// Method:        CalcPartWindowSize
// Origin:        SamplePart
//
// Description:    This method is called by the part to determine what size a new
//                window shoud be.
//------------------------------------------------------------------------------

SOM_Scope    Rect
SOMLINK        SamplePart__CalcPartWindowSize
             (
                SampleCode_SamplePart*        somSelf,
                Environment*                ev,
                ODFrame*                    sourceFrame
            )
{
    const ODSShort kOnePageWidth = 600;

    Rect windowRect;

    SampleCode_SamplePartData *somThis = SampleCode_SamplePartGetData(somSelf);
    SampleCode_SamplePartMethodDebug("SamplePart","CalcPartWindowSize");

    SOM_TRY

        ODRect        frameRect;
        ODShape*    frameShape;

        // If a source frame is given, the part is being asked to open one of
        // its display frames into a part window. Otherwise, we are being opened
        // as the root frame of the current document and should size the window
        // accordingly.

        // Set up the child window's size to be that of the display frame being opened.
        if ( sourceFrame )
        {
            TRY
                // Retrieve the fixed point bounding box for the frame.
                frameShape = ODFrame_AcquireFrameShape(sourceFrame, ev, kODNULL);
                CHECK_ENV(ev);
                ODShape_GetBoundingBox(frameShape, ev, &frameRect);
                CHECK_ENV(ev);
                ODReleaseObject(ev, frameShape);

                // Convert that into a Quickdraw rectangle.
                FixedToIntRect(&frameRect, &windowRect);
            CATCH_ALL
                ODSafeReleaseObject(frameShape);
                RERAISE;
            ENDTRY
        }
        // Otherwise, just open a large window.
        else
        {
            // (3 * kODLargeIconSize) prevents the window from covering the volume
            // icons on the desktop which is a violation of Macintosh HI Guidelines.

            SetRect(&windowRect, 0, 0,
                      ODQDGlobals.screenBits.bounds.right - (3 * kODLargeIconSize),
                      ODQDGlobals.screenBits.bounds.bottom
                          - GetMBarHeight() - kMacWindowTitleBarHeight - kALittleNudge);

            if ( windowRect.right - windowRect.left > kOnePageWidth )
                windowRect.right = windowRect.left + kOnePageWidth;
        }

    SOM_CATCH_ALL
    SOM_ENDTRY

    return windowRect;
}

//------------------------------------------------------------------------------
// Method:        CalcPartWindowPosition
// Origin:        SamplePart
//
// Description:    This method is called by the part to determine where to align
//                the new window (top left corner of the screen or tiled to a
//                frame).
//------------------------------------------------------------------------------

SOM_Scope    Rect
SOMLINK        SamplePart__CalcPartWindowPosition
             (
                SampleCode_SamplePart*        somSelf,
                Environment*                ev,
                ODFrame*                    frame,
                Rect*                        partWindowBounds
            )
{
    SampleCode_SamplePartData *somThis = SampleCode_SamplePartGetData(somSelf);
    SampleCode_SamplePartMethodDebug("SamplePart","CalcPartWindowPosition");

    SOM_TRY

        ODFacet*        activeFacet;
        ODFrame*        activeFrame;
        ODCanvas*        canvas;
        ODRect            bbox;
        Rect            bounds;
        ODShape*         frameShape = kODNULL;
        ODTransform*     windowFrameTransform = kODNULL;
        ODShape*         boundsShape = kODNULL;

        ODVolatile(frameShape);
        ODVolatile(boundsShape);
        ODVolatile(windowFrameTransform);

        // We need to know which facet of the frame we are opening to position
        // the part window.
        activeFacet = _GetActiveFacetForFrame(somSelf, ev, frame);
        CHECK_ENV(ev);

        // This should never occur, but if it did, it would be fatal.
        // So we will just pass back the same rectangle.
        THROW_IF_NULL(activeFacet);

        // For the purposes of tiling, we need the to know the area of the
        // document the frame occupies. We do this by getting the bouding
        // box and offsetting it by the aggregate external window transform
        // of the facet.

        TRY
            activeFrame = ODFacet_GetFrame(activeFacet, ev);
            CHECK_ENV(ev);
            frameShape = ODFrame_AcquireFrameShape(activeFrame, ev, kODNULL);
            CHECK_ENV(ev);
            windowFrameTransform = ODFacet_AcquireWindowFrameTransform(activeFacet, ev, kODNULL);
            CHECK_ENV(ev);
        CATCH_ALL
            ODSafeReleaseObject(frameShape);
            RERAISE;
        ENDTRY

        TRY
            boundsShape = CopyAndRelease(ev, frameShape);

            // Translate the bounds rect into window coordinates.
            ODShape_Transform(boundsShape, ev, windowFrameTransform);
            CHECK_ENV(ev);

            // Get and convert the bounding box into a QuickDraw rectangle.
            ODShape_GetBoundingBox(boundsShape, ev, &bbox);
            CHECK_ENV(ev);
            FixedToIntRect(&bbox, &bounds);

            ODReleaseObject(ev, boundsShape);
            ODReleaseObject(ev, windowFrameTransform);
        CATCH_ALL
            ODSafeReleaseObject(boundsShape);
            ODSafeReleaseObject(windowFrameTransform);
            RERAISE;
        ENDTRY

        // We then call our method to tile the child window.
        *partWindowBounds = TilePartWindow(ev, &bounds, partWindowBounds);

        // Set the port and origin so we can convert the rect to
        // global Window Mgr coordinates.
        canvas = ODFacet_GetCanvas(activeFacet, ev);
        CHECK_ENV(ev);
        SetPort(ODCanvas_GetQDPort(canvas, ev));
        SetOrigin(0,-kMacWindowTitleBarHeight);

        // Convert the local coordinates to global Window Mgr coordinates.
        LocalToGlobal((Point*)(&(partWindowBounds->top)));
        LocalToGlobal((Point*)(&(partWindowBounds->bottom)));

    SOM_CATCH_ALL
    SOM_ENDTRY

    return *partWindowBounds;
}

//------------------------------------------------------------------------------
// Method:        ZoomPartWindow
// Origin:        SamplePart
//
// Description:    This method is called by the part when a frame is being opened
//                or closed in the case that zooming rectangles should be shown.
//------------------------------------------------------------------------------

SOM_Scope    void
SOMLINK        SamplePart__ZoomPartWindow
             (
                SampleCode_SamplePart*        somSelf,
                Environment*                ev,
                   ODFrame*                    frame,
                   ODWindow*                    window,
                   ODBoolean                    openingWindow
               )
{
    const ODSShort kNumZoomSteps = 12;

    SOM_Trace("SamplePart","ZoomPartWindow");

    SOM_TRY

        Rect frameRect;
        Rect windowRect;
        Rect fromRect;
        Rect toRect;

        {
            // We need to know which facet of the frame we are opening to position
            // the child window.
            ODFacet* zoomFacet = kODNULL;

            TRY
                zoomFacet = _GetActiveFacetForFrame(somSelf, ev, frame);
            CATCH_ALL
            ENDTRY

            // In case there isn't an active facet for the frame.
            if ( zoomFacet == kODNULL )
            {
                ODFrameFacetIterator* iter = ODFrame_CreateFacetIterator(frame, ev);
                zoomFacet = ODFrameFacetIterator_First(iter, ev);
                ODDeleteObject_C(iter);
            }

            if ( zoomFacet != kODNULL )
            {
                ODShape*    boundsShape;
                ODFrame*    zoomFrame;
                ODCanvas*    canvas;
                ODRect        bbox;

                // For doing the zoom rects, we need the to know the area of the
                // document the frame occupies. We do this by getting the bouding
                // box and offsetting it by the aggregate external window transform
                // of the facet.
                ODTransform* windowFrameTransform =
                                    ODFacet_AcquireWindowFrameTransform(zoomFacet, ev, kODNULL);
                zoomFrame = ODFacet_GetFrame(zoomFacet, ev);
                boundsShape = CopyAndRelease(ev, ODFrame_AcquireFrameShape(zoomFrame, ev, kODNULL));

                // Translate the bounds rect into window coordinates.
                ODShape_Transform(boundsShape, ev, windowFrameTransform);

                // Get and convert the bounding box into a QuickDraw rectangle.
                ODShape_GetBoundingBox(boundsShape, ev, &bbox);
                FixedToIntRect(&bbox, &frameRect);

                // Set the port and origin so we can convert the rect to
                // global Window Mgr coordinates.
                canvas = ODFacet_GetCanvas(zoomFacet, ev);
                SetPort(ODCanvas_GetQDPort(canvas, ev));
                SetOrigin(0, 0);

                // Convert the local coordinates to global Window Mgr coordinates.
                LocalToGlobal((Point*) &frameRect.top);
                LocalToGlobal((Point*) &frameRect.bottom);

                ODReleaseObject(ev, windowFrameTransform);
                ODReleaseObject(ev, boundsShape);
            }
        }

        {
            ODPlatformWindow platformWindow = ODWindow_GetPlatformWindow(window, ev);

            windowRect = platformWindow->portRect;
            windowRect.top -= kMacWindowTitleBarHeight;

            // Set the port and origin so we can convert the rect to
            // global Window Mgr coordinates.
            SetPort(platformWindow);
            SetOrigin(0, 0);

            // Convert the local coordinates to global Window Mgr coordinates.
            LocalToGlobal((Point*) &windowRect.top);
            LocalToGlobal((Point*) &windowRect.bottom);
        }

        fromRect = openingWindow ? frameRect  : windowRect;
        toRect   = openingWindow ? windowRect : frameRect;

        if ( !openingWindow )
            ODWindow_Hide(window, ev);

        ZoomRects(&fromRect, &toRect, kNumZoomSteps,
                    openingWindow ? zoomAccelerate : zoomDecelerate);
    SOM_CATCH_ALL
    SOM_ENDTRY
}

//------------------------------------------------------------------------------
// Method:        GetActiveFacetForFrame
// Origin:        SamplePart
//
// Description:    This method is called by the part when it needs to know what the
//                current active facet is.
//
//                The part uses this method specifically to find the facet of a
//                source frame when opening a part window.
//------------------------------------------------------------------------------

SOM_Scope    ODFacet*
SOMLINK        SamplePart__GetActiveFacetForFrame
             (
                SampleCode_SamplePart*        somSelf,
                Environment*                ev,
                ODFrame*                    frame
            )
{
    ODFacet* facet = kODNULL;

    SampleCode_SamplePartData *somThis = SampleCode_SamplePartGetData(somSelf);
    SampleCode_SamplePartMethodDebug("SamplePart","GetActiveFacetForFrame");

    SOM_TRY

        ODFrameFacetIterator*     fiter = kODNULL;
        ODFacet*                selectedFacet = kODNULL;
        CFrameInfo*             frameInfo = kODNULL;

        ODVolatile( facet );

        frameInfo = (CFrameInfo*) ODFrame_GetPartInfo(frame, ev);
        CHECK_ENV(ev);

        // If the frame is active, and it should be, get the active facet
        // from the frame state info.
        if ( CFrameInfo_IsFrameActive(frameInfo) )
        {
            facet = CFrameInfo_GetActiveFacet(frameInfo);
        }
        else
        {
            // Otherwise, iterate over the display frames looking for one
            // that has an active facet... there should be at least one.
            fiter = ODFrame_CreateFacetIterator(frame, ev);
            CHECK_ENV(ev);

            for ( selectedFacet = ODFrameFacetIterator_First(fiter, ev);
                                   ODFrameFacetIterator_IsNotComplete(fiter, ev);
                  selectedFacet = ODFrameFacetIterator_Next(fiter, ev) )
            {
                if ( ODFacet_IsSelected(selectedFacet, ev) )
                {
                    facet = selectedFacet;
                    break;
                }
            }
            ODDeleteObject_C(fiter);
            CHECK_ENV(ev);
        }

        // If there are no active facets anywhere, this method should never
        // have been called, so signal an error.
        if ( facet == kODNULL )
            THROW(kODErrInvalidFrame);

    SOM_CATCH_ALL
        facet = kODNULL;
    SOM_ENDTRY

    return facet;
}

//==============================================================================
#pragma mark    • Imaging •
//==============================================================================

//------------------------------------------------------------------------------
// Method:        FacetAdded
// Origin:        ODPart
//
// Description:    This method is called when any part adds a facet to
//                one of our display frames.
//
//                The part calls ViewTypeChanged to load the appropriate
//                resource for display in this facet and then activates
//                the frame if we are the root part of an active window.
//------------------------------------------------------------------------------

SOM_Scope    void
SOMLINK        SamplePart__FacetAdded
            (
                SampleCode_SamplePart*        somSelf,
                Environment*                ev,
                ODFacet*                    facet
            )
{
    SampleCode_SamplePartData *somThis = SampleCode_SamplePartGetData(somSelf);
    SampleCode_SamplePartMethodDebug("SamplePart","FacetAdded");

    SOM_TRY

        ODFrame*     frame        = kODNULL;
        CFrameInfo* frameInfo     = kODNULL;

        frame = ODFacet_GetFrame(facet, ev);
        CHECK_ENV(ev);
        frameInfo = (CFrameInfo*) ODFrame_GetPartInfo(frame, ev);
        CHECK_ENV(ev);

        // If a root facet is being added, the frame should be activated when the
        // window is "selected". This prevents OpenDoc from getting into an
        // ambiguous state of no part having the selection focus.

        if ( ODFrame_IsRoot(frame, ev) )
        {
            CFrameInfo_SetActiveFacet(frameInfo, facet);
            CFrameInfo_SetFrameReactivate(frameInfo, kODTrue);
        }
        CHECK_ENV(ev);

        // If a frame had all of its facets removed, the frame would have
        // hidden any of its part windows. If the frame becomes visible again,
        // by having a facet added to it, we will "show" the part window for
        // the frame.

        if ( (CountFramesFacets(ev, frame) == 1) )
        {
            ODWindow* window = CFrameInfo_AcquirePartWindow(frameInfo, ev);
            CHECK_ENV(ev);

            if ( window )
            {
                ODWindow_Show(window, ev);
                CHECK_ENV(ev);
            }

            ODReleaseObject(ev, window);
        }
        CHECK_ENV(ev);

    SOM_CATCH_ALL
    SOM_ENDTRY
}

//------------------------------------------------------------------------------
// Method:        FacetRemoved
//
// Description:    This method is called when any part removes a facet
//                from one of our display frames.
//
//                The part just removes the "active" note from the
//                appropriate display frame if necessary since this
//                facet will not be available, nor active, again.
//------------------------------------------------------------------------------

SOM_Scope    void
SOMLINK        SamplePart__FacetRemoved
            (
                SampleCode_SamplePart*        somSelf,
                Environment*                ev,
                ODFacet*                    facet
            )
{
    SampleCode_SamplePartData *somThis = SampleCode_SamplePartGetData(somSelf);
    SampleCode_SamplePartMethodDebug("SamplePart","FacetRemoved");

    SOM_TRY

        ODFrame*     frame         = kODNULL;
        ODFrame*     containingFrame = kODNULL;
        CFrameInfo* frameInfo     = kODNULL;
        ODWindow*    window;

        ODVolatile(window);

        frame = ODFacet_GetFrame(facet, ev);
        CHECK_ENV(ev);
        frameInfo = (CFrameInfo*) ODFrame_GetPartInfo(frame, ev);
        CHECK_ENV(ev);
        containingFrame = ODFrame_AcquireContainingFrame(frame, ev);
        CHECK_ENV(ev);

        TRY
            // If the facet was the active facet, it can no longer be.
            if( ODObjectsAreEqual(ev, CFrameInfo_GetActiveFacet(frameInfo), facet) )
                CFrameInfo_SetActiveFacet(frameInfo, kODNULL);

            // If a frame has all of its facets removed, the frame becomes
            // "hidden". If the frame a part window, the part window should also
            // be hidden.

            if ( (CountFramesFacets(ev, frame) == 0) &&
                    (containingFrame == kODNULL) )
            {
                window = CFrameInfo_AcquirePartWindow(frameInfo, ev);
                CHECK_ENV(ev);

                if ( window )
                {
                    ODWindow_Hide(window, ev);
                    CHECK_ENV(ev);
                }

                ODReleaseObject(ev, window);
            }
            CHECK_ENV(ev);

            ODReleaseObject(ev, containingFrame);

        CATCH_ALL
            ODSafeReleaseObject(window);
            ODSafeReleaseObject(containingFrame);
            RERAISE;
        ENDTRY

    SOM_CATCH_ALL
    SOM_ENDTRY
}

//------------------------------------------------------------------------------
// Method:        Draw
// Origin:        ODPart
//
// Description:    This method is called when a facet of a part's display
//                frame intersects the invalidated portion of an OpenDoc
//                window. The invalidShape parameter passed in is the
//                portion of the facet which has been invalidated.
//
//                The part sets up the drawing environment using a
//                C++ helper class (CFocus) and then calls the
//                appropriate drawing method based on the frame's
//                viewType.
//------------------------------------------------------------------------------

SOM_Scope    void
SOMLINK        SamplePart__Draw
            (
                SampleCode_SamplePart*        somSelf,
                Environment*                ev,
                ODFacet*                    facet,
                ODShape*                    invalidShape
            )
{
    SampleCode_SamplePartData *somThis = SampleCode_SamplePartGetData(somSelf);
    SampleCode_SamplePartMethodDebug("SamplePart","Draw");

    SOM_TRY

        ODFrame*    frame;
        ODTypeToken view;
        FocusState    focusState;

        // Focus the port and origin for drawing in our facet.
        // Note that this instance of the CFocusDrawingEnv class
        // is being allocated on the stack. When the execution
        // leaves the scope of this method, the destructor (which
        // cleans up the drawing environment) is automatically
        // called.
        BeginFocus(ev, &focusState, facet, kODFalse, kODNULL, kODNULL);
        CHECK_ENV(ev);

        frame = ODFacet_GetFrame(facet, ev);
        CHECK_ENV(ev);
        view = ODFrame_GetViewType(frame, ev);
        CHECK_ENV(ev);

        if ( view == gGlobals->fLargeIconView || view == gGlobals->fSmallIconView )
            _DrawIconView(somSelf, ev, facet);
        else if ( view == gGlobals->fThumbnailView )
            _DrawThumbnailView(somSelf, ev, facet);
        else
            _DrawFrameView(somSelf, ev, facet);

        // Cleanup the structure created during port focusing.
        EndFocus(&focusState);

    SOM_CATCH_ALL
    SOM_ENDTRY
}

//------------------------------------------------------------------------------
// Method:        DrawFrameView
// Origin:        SamplePart
//
// Description:    This method is called by the part when the frame being
//                drawn is in "frame" view.
//
//                SamplePart really has not intrisic content. However,
//                to provide some visual display, we draw the class name
//                at 80% of the frame's current height using an outlined
//                font.
//------------------------------------------------------------------------------

SOM_Scope    void
SOMLINK        SamplePart__DrawFrameView
             (
                SampleCode_SamplePart*        somSelf,
                Environment*                ev,
                ODFacet*                    facet
            )
{
    SampleCode_SamplePartData *somThis = SampleCode_SamplePartGetData(somSelf);
    SampleCode_SamplePartMethodDebug("SamplePart","DrawFrameView");

    SOM_TRY

        GrafPtr        port;
        ODFrame*     frame = kODNULL;
        ODUShort     frameHeight;
        ODUShort     frameWidth;
        ODShape*    frameShape;

        ODVolatile(frameShape);

        GetPort(&port);
        EraseRect(&port->portRect);

        // If the facet being draw is attached to a source frame in
        // another window, we need to access the source frame to determine
        // what size to draw the content.

        {
            CFrameInfo* frameInfo = kODNULL;

            frame = ODFacet_GetFrame(facet, ev);
            CHECK_ENV(ev);
            frameInfo = (CFrameInfo*) ODFrame_GetPartInfo(frame, ev);
            if ( CFrameInfo_HasSourceFrame(frameInfo) )
                frame = CFrameInfo_GetSourceFrame(frameInfo, ev);
            else
                frame = ODFacet_GetFrame(facet, ev);
            CHECK_ENV(ev);
        }

        TRY
            RgnHandle    frameRgn;
            ODCanvas*     biasCanvas;

            ODVolatile(frameShape);

            // Get the facet's canvas so shapes are returned in the correct
            // coordinate system.
            biasCanvas = ODFacet_GetCanvas(facet, ev);
            CHECK_ENV(ev);

            // Calculate font height for drawing.
            frameShape = ODFrame_AcquireFrameShape(frame, ev, biasCanvas);
            CHECK_ENV(ev);
            frameRgn = ODShape_GetQDRegion(frameShape, ev);
            CHECK_ENV(ev);
            frameHeight = (**frameRgn).rgnBBox.bottom - (**frameRgn).rgnBBox.top;
            frameWidth = (**frameRgn).rgnBBox.right - (**frameRgn).rgnBBox.left;
            ODReleaseObject(ev, frameShape);

        CATCH_ALL
            ODSafeReleaseObject(frameShape);
            RERAISE;
        ENDTRY

        {
            ODUShort     size;
            ODUShort     font;
            Style         face;
            ODSLong     rfRef;
            FontInfo    fontInfo;
            Str63        defaultString;

            // Save off port chararcteristics so we can restore it later.
            size = port->txSize;
            font = port->txFont;
            face = port->txFace;

            // Set the font size to almost fill the frame.
            TextSize((ODUShort)(frameHeight * 0.8));
            // Use the default Application font for this script system.
            TextFont(1);
            TextFace(bold + condense);

            GetFontInfo(&fontInfo);

            rfRef = BeginUsingLibraryResources();
            {
                PenState penState;

                GetPenState(&penState);

                PenNormal();
                GetIndString(defaultString, kMenuStringResID, kDefaultContent1ID);
                MoveTo((frameWidth / 2) - (StringWidth(defaultString) / 2),
                            frameHeight - (fontInfo.descent - 2));
                DrawString(defaultString);

                // If the part is selected, fill the background with
                // the highlight color.
                if ( ODFacet_GetHighlight(facet, ev) == kODFullHighlight )
                {
                    UInt8 mode = LMGetHiliteMode();
                    BitClr(&mode,pHiliteBit);
                    LMSetHiliteMode(mode);
                    InvertRect(&port->portRect);
                }

                TextMode(srcXor);
                TextSize(24);
                TextFace(bold + extend);

                GetIndString(defaultString, kMenuStringResID, kDefaultContent2ID);
                MoveTo((frameWidth / 2) - (StringWidth(defaultString) / 2),
                            (frameHeight / 2) + 6);
                DrawString(defaultString);

                SetPenState(&penState);
            }
            EndUsingLibraryResources(rfRef);

            // Restore port chararcteristics.
            SetPort(port);
            port->txSize = size;
            port->txFont = font;
            port->txFace = face;
        }

    SOM_CATCH_ALL
    SOM_ENDTRY
}

//--------------------------------------------------------------------
// Method:        DrawIconView
// Origin:        SamplePart
//
// Description:    This method is called by the part when the frame being
//                drawn is in "standard icon" view.
//
//                The part uses the Icon Utilities toolbox manager to
//                aid in drawing icons in active windows. The Guidelines
//                require a different appearance for selected icons in
//                inactive windows, which we do manually.
//------------------------------------------------------------------------------

SOM_Scope    void
SOMLINK        SamplePart__DrawIconView
             (
                SampleCode_SamplePart*        somSelf,
                Environment*                ev,
                ODFacet*                    facet
            )
{
    SampleCode_SamplePartMethodDebug("SamplePart","DrawIconView");

    SOM_TRY

        Rect                iconRect;
        IconTransformType     transformType = ttNone;
        CFrameInfo*            frameInfo;
        ODFrame*            frame;
        ODTypeToken            viewType;
        ODWindow*             window;
        ODSLong             res;

        frame = ODFacet_GetFrame(facet, ev);
        viewType = ODFrame_GetViewType(frame, ev);
        frameInfo = (CFrameInfo*) ODFrame_GetPartInfo(frame, ev);

        // Check to see if the facet is selected
        if ( ODFacet_GetHighlight(facet, ev) == kODFullHighlight )
            transformType = ttSelected;
        CHECK_ENV(ev);

        // Check to see if the frame has been opened into a part window.
        window = CFrameInfo_AcquirePartWindow(frameInfo, ev);
        if ( window && ODWindow_IsShown(window,ev) )
            transformType |= ttOpen;
        CHECK_ENV(ev);

        // Draw the icon.
        if ( viewType == gGlobals->fLargeIconView )
            SetRect(&iconRect, 0, 0, kODLargeIconSize, kODLargeIconSize);
        else // ( viewType == gGlobals->fSmallIconView )
            SetRect(&iconRect, 0, 0, kODSmallIconSize, kODSmallIconSize);

        res = BeginUsingLibraryResources();
            PlotIconID(&iconRect, atAbsoluteCenter, transformType, kBaseResourceID);
        EndUsingLibraryResources(res);

    SOM_CATCH_ALL
    SOM_ENDTRY
}

//--------------------------------------------------------------------
// Method:        DrawThumbnailView
// Origin:        SamplePart
//
// Description:    This method is called by the part when the frame being
//                drawn is in "thumbnail" view.
//
//                The part uses a picture for its thumbnail view because
//                it has no intrinsic content. A picture resource is
//                probably not sufficient for parts with real content.
//------------------------------------------------------------------------------

SOM_Scope    void
SOMLINK        SamplePart__DrawThumbnailView
             (
                SampleCode_SamplePart*        somSelf,
                Environment*                ev,
                ODFacet*                    facet
            )
{
    SampleCode_SamplePartMethodDebug("SamplePart","DrawThumbnailView");

    SOM_TRY

        PicHandle thumbnail;
        Rect bounds;

        // Create or retrieve a cached thumbnail picture.
        thumbnail = _GenerateThumbnail(somSelf, ev, ODFacet_GetFrame(facet, ev));

        bounds = (**thumbnail).picFrame;
        DrawPicture(thumbnail, &bounds);

    SOM_CATCH_ALL
    SOM_ENDTRY
}

//--------------------------------------------------------------------
// Method:        GenerateThumbnail
// Origin:        SamplePart
//
// Description:    This method is called by the part to generate a
//                thumbnail view from the current content.
//
//                The part has no content, so we merely load a picture.
//-------------------------------------------------------------------

SOM_Scope    PicHandle
SOMLINK        SamplePart__GenerateThumbnail
             (
                SampleCode_SamplePart*        somSelf,
                Environment*                ev,
                ODFrame*                    frame
            )
{
    SampleCode_SamplePartMethodDebug("SamplePart","GenerateThumbnail");

    SOM_TRY

        if ( gGlobals->fThumbnail == kODNULL )
        {
            // In cases where a part has been instantiated from scratch and has no
            // content (yet), it is appropriate to display a PICT or some graphic
            // in place of a "real" thumbnail.

            LoadThumbnail(ev, &gGlobals->fThumbnail);

            // If we were unable to load the PICT resource for whatever reason
            // we will default back to a "frame" view and throw the Resource
            // Manager error as an exception.
            if ( gGlobals->fThumbnail == kODNULL )
            {
                ODFrame_ChangeViewType(frame, ev, gGlobals->fFrameView);
                CHECK_ENV(ev);

                // There is a bug in ResError, when resources are not found,
                // which may cause noErr to be returned. If that is the case,
                // we throw resNotFound.
                THROW_IF_ERROR((ODError)ResError());
                THROW(resNotFound);
            }
        }

    SOM_CATCH_ALL
    SOM_ENDTRY

    return (PicHandle)gGlobals->fThumbnail;
}

//--------------------------------------------------------------------
// Method:        GeometryChanged
// Origin:        ODPart
//
// Description:    This method is called when the ExternalTransform or
//                ClipShape of a facet on one this part's display frames
//                changes.
//-------------------------------------------------------------------

SOM_Scope void  SOMLINK SamplePart__GeometryChanged(SampleCode_SamplePart *somSelf,
            Environment     *ev,
            ODFacet*         facet,
            ODBoolean         clipShapeChanged,
            ODBoolean         externalTransformChanged /* unused */ )
{
    SampleCode_SamplePartMethodDebug("SamplePart","GeometryChanged");

    SOM_TRY

        if ( clipShapeChanged )
        {
            // Specifying kODNULL means to invalidate the clipShape (which was
            // calculated from the usedShape).
            ODFacet_Invalidate(facet, ev, kODNULL, kODNULL);
            CHECK_ENV(ev);
        }

    SOM_CATCH_ALL
    SOM_ENDTRY
}

//------------------------------------------------------------------------------
// Method:        HighlightChanged
// Origin:        ODPart
//
// Description:    This method is called when a facet....
//------------------------------------------------------------------------------

SOM_Scope    void
SOMLINK        SamplePart__HighlightChanged
            (
                SampleCode_SamplePart*        somSelf,
                Environment*                ev,
                ODFacet*                    facet
            )
{
    ODFrame* frame;

    SampleCode_SamplePartMethodDebug("SamplePart","HighlightChanged");

    SOM_TRY

        frame = ODFacet_GetFrame(facet, ev);
        CHECK_ENV(ev);

        // The frame view has no "special" drawing characteristics
        // when opened or selected, so we don't need to update our
        // content.

        if ( ODFrame_GetViewType(frame, ev) != gGlobals->fFrameView )
            ODFrame_Invalidate(frame, ev, kODNULL, kODNULL);
        CHECK_ENV(ev);

    SOM_CATCH_ALL
    SOM_ENDTRY
}

//==============================================================================
#pragma mark    • Activation •
//==============================================================================

//------------------------------------------------------------------------------
// Method:        BeginRelinquishFocus
// Origin:        ODPart
//
// Description:    This method is called when another part (or possibly
//                ourself) is requesting a focus for one of its display
//                frames. Returning true means we are willing to give
//                up the requested focus.
//
//                The part willingly gives up any focus unless it is the
//                modal focus which we don't want to give up until we
//                are completely done displaying a modal dialog.
//------------------------------------------------------------------------------

SOM_Scope    ODBoolean
SOMLINK        SamplePart__BeginRelinquishFocus
            (
                SampleCode_SamplePart*        somSelf,
                Environment*                ev,
                ODTypeToken                    focus,
                ODFrame*                    ownerFrame, /* unused */
                ODFrame*                    proposedFrame
            )
{
    ODBoolean     willRelinquish = kODTrue;

    SampleCode_SamplePartMethodDebug("SamplePart","BeginRelinquishFocus");

    SOM_TRY

        // Another part is trying to put up a Modal dialog while we
        // are currently displaying ours. Deny the request.
        if ( focus == gGlobals->fModalFocus )
        {
            ODPart* proposedPart = kODNULL;

            proposedPart = ODFrame_AcquirePart(proposedFrame, ev);
            CHECK_ENV(ev);
            if ( ODObjectsAreEqual(ev, proposedPart, somSelf) == kODFalse )
                willRelinquish =  kODFalse;
            ODReleaseObject(ev, proposedPart);
        }

    SOM_CATCH_ALL
    SOM_ENDTRY

    return willRelinquish;
}

//------------------------------------------------------------------------------
// Method:        CommitRelinquishFocus
// Origin:        ODPart
//
// Description:    This method is called when it is actually time to give
//                up a focus that had been requested by another part (or
//                possibly ourself).
//
//                The part calls its FocusLost method to handle the
//                "reliquishing" of the particular focus.
//------------------------------------------------------------------------------

SOM_Scope    void
SOMLINK        SamplePart__CommitRelinquishFocus
            (
                SampleCode_SamplePart*        somSelf,
                Environment*                ev,
                ODTypeToken                    focus,
                ODFrame*                    ownerFrame,
                ODFrame*                    proposedFrame /* unused */
            )
{
    SampleCode_SamplePartMethodDebug("SamplePart","CommitRelinquishFocus");

    SOM_TRY

        // We agreed to give up our FocusSet and now we are being asked to
        // do so.
        _FocusLost(somSelf, ev, focus, ownerFrame);
        CHECK_ENV(ev);

    SOM_CATCH_ALL
    SOM_ENDTRY
}

//------------------------------------------------------------------------------
// Method:        AbortRelinquishFocus
// Origin:        ODPart
//
// Description:    This method is called when another part (or possibly
//                ourself) requested a focus for one of its display
//                frames, but we returned kODFalse from
//                BeginRelinqishFocus for one, or all, of the requested
//                focus. At this point, we are being told to resume
//                ownership of the focus.
//
//                The part calls its FocusAcquired method to handle the
//                re-"acquisition" of the particular focus.
//------------------------------------------------------------------------------

SOM_Scope    void
SOMLINK        SamplePart__AbortRelinquishFocus
            (
                SampleCode_SamplePart*        somSelf,
                Environment*                ev,
                ODTypeToken                    focus, /* unused */
                ODFrame*                    ownerFrame, /* unused */
                ODFrame*                    proposedFrame /* unused */
            )
{
    SampleCode_SamplePartMethodDebug("SamplePart","AbortRelinquishFocus");

    // Some parts may have suspended some events in the BeginRelinquishFocus
    // method. If so, they would resume those events here.
}

//--------------------------------------------------------------------
// Method:        FocusAcquired
// Origin:        ODPart
//
// Description:    This method is called when the Arbitrator has
//                registered us as the "owner" of the particular focus.
//                This can occur if a focus is requested, or if a focus
//                is transfered to one of the part's display frames.
//
//                The part will request the other foci it needs to be "active". If
//                the part is successful, we notify ourself to become active.
//------------------------------------------------------------------------------

SOM_Scope    void
SOMLINK        SamplePart__FocusAcquired
            (
                SampleCode_SamplePart*        somSelf,
                Environment*                ev,
                ODTypeToken                    focus,
                ODFrame*                    ownerFrame
            )

{
    SampleCode_SamplePartData *somThis = SampleCode_SamplePartGetData(somSelf);
    SampleCode_SamplePartMethodDebug("SamplePart","FocusAcquired");

    SOM_TRY

        ODSession*        session;
        ODArbitrator*     arbitrator;

        session =  ODGetSessionFromPart(ev, _fSelf);
        CHECK_ENV(ev);
        arbitrator = ODSession_GetArbitrator(session, ev);
        CHECK_ENV(ev);

        if ( ODArbitrator_RequestFocusSet(arbitrator, ev, gGlobals->fUIFocusSet, ownerFrame) )
        {
            _PartActivated(somSelf, ev, ownerFrame);
            CHECK_ENV(ev);
        }
        CHECK_ENV(ev);

    SOM_CATCH_ALL
    SOM_ENDTRY
}

//------------------------------------------------------------------------------
// Method:        FocusLost
// Origin:        ODPart
//
// Description:    This method is called when the Arbitrator has
//                unregistered us as the "owner" of the particular
//                focus.
//
//                The part unmarks the active frame if the selection
//                focus is lost.
//------------------------------------------------------------------------------

SOM_Scope    void
SOMLINK        SamplePart__FocusLost
            (
                SampleCode_SamplePart*        somSelf,
                Environment*                ev,
                ODTypeToken                    focus,
                ODFrame*                    ownerFrame
            )
{
    SampleCode_SamplePartMethodDebug("SamplePart","FocusLost");

    SOM_TRY

        if ( focus == gGlobals->fSelectionFocus )
        {
            CFrameInfo* frameInfo = (CFrameInfo*) ODFrame_GetPartInfo(ownerFrame, ev);
            CFrameInfo_SetFrameActive(frameInfo, kODFalse);
        }

    SOM_CATCH_ALL
    SOM_ENDTRY
}

//------------------------------------------------------------------------------
// Method:        RelinquishAllFoci
// Origin:        SamplePart
//
// Description:    This method is called when a frame is going away. The method
//                relinquishes all foci the frame owns.
//------------------------------------------------------------------------------

SOM_Scope    void
SOMLINK        SamplePart__RelinquishAllFoci
            (
                SampleCode_SamplePart*        somSelf,
                Environment*                ev,
                ODFrame*                    frame
            )
{
    SampleCode_SamplePartData *somThis = SampleCode_SamplePartGetData(somSelf);
    SampleCode_SamplePartMethodDebug("SamplePart","RelinquishAllFoci");

    SOM_TRY

        ODSession* session = kODNULL;
        ODArbitrator* arbitrator = kODNULL;
        ODFrame* selectionFocusFrame = kODNULL;
        ODFrame* menuFocusFrame = kODNULL;

        ODVolatile(selectionFocusFrame);
        ODVolatile(menuFocusFrame);

        session =  ODGetSessionFromPart(ev, _fSelf);
        CHECK_ENV(ev);
        arbitrator = ODSession_GetArbitrator(session, ev);
        CHECK_ENV(ev);

        TRY
            selectionFocusFrame = ODArbitrator_AcquireFocusOwner(arbitrator, ev, gGlobals->fSelectionFocus);
            CHECK_ENV(ev);
            if ( ODObjectsAreEqual(ev, selectionFocusFrame, frame) )
            {
                ODArbitrator_RelinquishFocus(arbitrator, ev, gGlobals->fSelectionFocus, frame);
                CHECK_ENV(ev);
                _FocusLost(somSelf, ev, gGlobals->fSelectionFocus, frame);
                CHECK_ENV(ev);
            }
            ODReleaseObject( ev, selectionFocusFrame);
        CATCH_ALL
            ODSafeReleaseObject(selectionFocusFrame);
        ENDTRY

        TRY
            menuFocusFrame = ODArbitrator_AcquireFocusOwner(arbitrator, ev, gGlobals->fMenuFocus);
            CHECK_ENV(ev);
            if ( ODObjectsAreEqual(ev, menuFocusFrame, frame) )
            {
                ODArbitrator_RelinquishFocus(arbitrator, ev, gGlobals->fMenuFocus, frame);
                CHECK_ENV(ev);
                _FocusLost(somSelf, ev, gGlobals->fMenuFocus, frame);
                CHECK_ENV(ev);
            }

            ODReleaseObject( ev, menuFocusFrame );
        CATCH_ALL
            ODSafeReleaseObject( menuFocusFrame );
        ENDTRY

    SOM_CATCH_ALL
    SOM_ENDTRY
}

//------------------------------------------------------------------------------
// Method:        PartActivated
// Origin:        SamplePart
//
// Description:    This method is called when the part has successfully acquired
//                the set of foci which allow it to "run".
//------------------------------------------------------------------------------

SOM_Scope     void
SOMLINK     SamplePart__PartActivated
            (
                SampleCode_SamplePart*    somSelf,
                Environment*            ev,
                ODFrame*                 frame
            )
{
    SampleCode_SamplePartData *somThis = SampleCode_SamplePartGetData(somSelf);
    SampleCode_SamplePartMethodDebug("SamplePart","PartActivated");

    SOM_TRY

        CFrameInfo*    frameInfo = kODNULL;

        // We are required to re-validate the menubar before displaying it because
        // any part can/could swap the base menubar at any time.
        if ( ODMenuBar_IsValid(gGlobals->fMenuBar, ev) == kODFalse )
        {
            ODSession* session = kODNULL;
            ODWindowState*    windowState = kODNULL;

            ODReleaseObject(ev, gGlobals->fMenuBar);
            session =  ODGetSessionFromPart(ev, _fSelf);
            CHECK_ENV(ev);
            windowState = ODSession_GetWindowState(session, ev);
            CHECK_ENV(ev);
            gGlobals->fMenuBar = ODWindowState_CopyBaseMenuBar(windowState, ev);
            CHECK_ENV(ev);

            // After copying the "new" base menu bar, don't forget to re-install
            // your part's menus.
        }
        CHECK_ENV(ev);

        // Display our menu bar.
        ODMenuBar_Display(gGlobals->fMenuBar, ev);
        CHECK_ENV(ev);

        // And set our "active" state.
        frameInfo = (CFrameInfo*) ODFrame_GetPartInfo(frame, ev);
        CHECK_ENV(ev);
        CFrameInfo_SetFrameActive(frameInfo, kODTrue);

    SOM_CATCH_ALL
    SOM_ENDTRY
}

//------------------------------------------------------------------------------
// Method:        ActivateFrame
// Origin:        SamplePart
//
// Description:    This method is called by the part when a kODEvtMouseUp
//                occurs in an inactive frame in an active window, and
//                when an OpenDoc document comes forward.
//
//                The part activates the frame by requesting the
//                UIFocusSet (created in Initialize) and by calling
//                FocusAcquired if we were successful. The method
//                returns true if no problems were encountered as a
//                signal to the caller that the frame is now "active".
//------------------------------------------------------------------------------

SOM_Scope    ODBoolean
SOMLINK        SamplePart__ActivateFrame
             (
                SampleCode_SamplePart*        somSelf,
                Environment*                ev,
                ODFrame*                    frame
            )
{
    ODBoolean activated = kODFalse;

    SampleCode_SamplePartData *somThis = SampleCode_SamplePartGetData(somSelf);
    SampleCode_SamplePartMethodDebug("SamplePart","ActivateFrame");

    SOM_TRY

        ODSession* session = kODNULL;
        ODArbitrator* arbitrator = kODNULL;

        session = ODGetSessionFromPart(ev,_fSelf);
        CHECK_ENV(ev);
        arbitrator = ODSession_GetArbitrator(session, ev);
        CHECK_ENV(ev);

        // Request the set of foci necessary to become active.
        if ( ODArbitrator_RequestFocusSet(arbitrator, ev, gGlobals->fUIFocusSet,frame) )
        {
            _PartActivated(somSelf, ev, frame);
            CHECK_ENV(ev);
            // We were able to become active.
            activated = kODTrue;
        }
        CHECK_ENV(ev);

    SOM_CATCH_ALL
        activated =  kODFalse;
    SOM_ENDTRY

    return activated;
}

//--------------------------------------------------------------------
// Method:        WindowActivating
// Origin:        SamplePart
//
// Description:    This method is called by the part when a process
//                switch event (kODEvtOS) occurs.
//
//                The part records the active frame, if any of the
//                display frames were active, so that the frame can be
//                re-activated when the document is switched into the
//                foreground.
//-------------------------------------------------------------------

SOM_Scope    void
SOMLINK        SamplePart__WindowActivating
             (
                SampleCode_SamplePart*        somSelf,
                Environment*                ev,
                ODFrame*                    frame,
                ODBoolean                    activating
            )
{
    SampleCode_SamplePartMethodDebug("SamplePart","WindowActivating");

    SOM_TRY

        CFrameInfo* frameInfo = (CFrameInfo*) ODFrame_GetPartInfo(frame, ev);
        CHECK_ENV(ev);

        // The window is being activated and we had the selection focus when
        // the window was deactivated, so request it again.
        if ( activating && CFrameInfo_FrameNeedsReactivating(frameInfo) )
        {
            _ActivateFrame(somSelf, ev, frame);
            CHECK_ENV(ev);

            CFrameInfo_SetFrameReactivate(frameInfo, kODFalse);
        }
        // The window is being deactivated and we have the active part.
        // So give up our foci and remind ourselves that we need to request
        // the focus when the window is reactivated.
        else if ( !activating && CFrameInfo_IsFrameActive(frameInfo) )
        {
            CFrameInfo_SetFrameReactivate(frameInfo, kODTrue);
        }

    SOM_CATCH_ALL
    SOM_ENDTRY
}

//==============================================================================
#pragma mark    • Event Handling •
//==============================================================================

//------------------------------------------------------------------------------
// Method:        HandleEvent
// Origin:        ODPart
//
// Description:    The method is called when an event, which falls into
//                the category of an owned focus, occurs. The two
//                exceptions to this are "mouse movement" events and
//                embedded frame events, which can occur when a part
//                owns no foci.
//
//                The part returns true if the event was handled.
//------------------------------------------------------------------------------

SOM_Scope    ODBoolean
SOMLINK        SamplePart__HandleEvent
            (
                SampleCode_SamplePart*        somSelf,
                Environment*                ev,
                ODEventData*                event,
                ODFrame*                    frame,
                ODFacet*                    facet,
                ODEventInfo*                eventInfo)
{
    ODBoolean eventHandled = kODFalse;

    SampleCode_SamplePartMethodDebug("SamplePart","HandleEvent");

    SOM_TRY

        // Event handling is basically the same as standard Macintosh applications,
        // except that the events have been renamed for cross-platform compatability.

        switch ( event->what ) {
            case kODEvtMouseDown:
            case kODEvtMouseUp:
                eventHandled = _HandleMouseEvent(somSelf, ev, event, facet, eventInfo);
                CHECK_ENV(ev);
                break;

            case kODEvtMenu:
                eventHandled = _HandleMenuEvent(somSelf, ev, event, frame);
                CHECK_ENV(ev);
                break;

            case kODEvtActivate:
                // We are being notified that a window we are display in has
                // just been de/activated (un/hilighted).
                _WindowActivating(somSelf, ev, frame, (event->modifiers & activeFlag ));
                CHECK_ENV(ev);
                eventHandled = kODTrue;
                break;

            case kODEvtMouseEnter:
            case kODEvtMouseLeave:
                SetCursor(&(ODQDGlobals.arrow));
                eventHandled = kODTrue;
                break;

            case kODEvtMouseWithin:
                eventHandled = kODTrue;
                break;

            // Other events a part might handle
            case kODEvtNull:
            case kODEvtMouseDownEmbedded:
            case kODEvtMouseUpEmbedded:
            case kODEvtMouseDownBorder:
            case kODEvtMouseUpBorder:
            case kODEvtWindow:
            case kODEvtKeyDown:
            case kODEvtKeyUp:
            case kODEvtAutoKey:
            case kODEvtDisk:
            case kODEvtOS:

            default:
                break;
        }

    SOM_CATCH_ALL
        eventHandled = kODFalse;
    SOM_ENDTRY

    return eventHandled;
}

//------------------------------------------------------------------------------
// Method:        AdjustMenus
// Origin:        ODPart
//
// Description:    This method is called when a kODEvtMouseDown event
//                occurs in the menubar and the part owns the "menu"
//                focus.
//
//                The part enables the appropriate items for its current
//                state and updates the menu items to reflect this
//                editor.
//------------------------------------------------------------------------------

SOM_Scope    void
SOMLINK        SamplePart__AdjustMenus
            (
                SampleCode_SamplePart*        somSelf,
                Environment*                ev,
                ODFrame*                    frame
            )
{
    SampleCode_SamplePartData *somThis = SampleCode_SamplePartGetData(somSelf);
    SampleCode_SamplePartMethodDebug("SamplePart","AdjustMenus");

    SOM_TRY

        ODSession*         session = kODNULL;
        ODArbitrator*     arbitrator = kODNULL;
        ODWindowState*    windowState = kODNULL;
        ODIText*        menuItem = kODNULL;
        ODFrame*         menuOwner = kODNULL;

        session = ODGetSessionFromPart(ev,_fSelf);
        CHECK_ENV(ev);

        // The menubar object always calls the root part's AdjustMenus method before
        // calling the menu focus owner's. Because of this, we need to validate the
        // menubar in the case where we are the root part.
        if ( ODFrame_IsRoot(frame, ev) )
        {
            // We are required to re-validate the menubar before displaying it because
            // any part can/could swap the base menubar at any time.
            if ( ODMenuBar_IsValid(gGlobals->fMenuBar, ev) == kODFalse )
            {
                ODReleaseObject(ev, gGlobals->fMenuBar);
                windowState = ODSession_GetWindowState(session, ev);
                CHECK_ENV(ev);
                gGlobals->fMenuBar = ODWindowState_CopyBaseMenuBar(windowState, ev);
                CHECK_ENV(ev);

                // After copying the "new" base menu bar, don't forget to re-install
                // your part's menus.
            }
            CHECK_ENV(ev);
        }
        CHECK_ENV(ev);

        // Enable the "View As Window" command if the frame is not the root
        // frame of the window.
        ODMenuBar_EnableCommand(gGlobals->fMenuBar, ev, kODCommandViewAsWin, !ODFrame_IsRoot(frame, ev));
        CHECK_ENV(ev);

        TRY
            arbitrator = ODSession_GetArbitrator(session, ev);
            menuOwner = ODArbitrator_AcquireFocusOwner(arbitrator, ev, gGlobals->fMenuFocus);

            // There is no need to load a resource, create an ODIText object, set the menubar,
            // and cleanup, if we don't own the menu focus.
            if ( ODObjectsAreEqual(ev, frame, menuOwner) )
            {
                Str63         text;
                // Get the "about" string from our library's resources.
                // (note: ODGetIndString focuses the resource fork for us)
                ODGetIndString(text, kMenuStringResID, kAboutTextID);
                // Create an IText object to pass into the menubar.
                menuItem = CreateITextPString(gGlobals->fEditorsScript, gGlobals->fEditorsLanguage, (StringPtr)&text);
                ODMenuBar_SetItemString(gGlobals->fMenuBar, ev, kODCommandAbout, menuItem);
                DisposeIText(menuItem);
                CHECK_ENV(ev);
            }
            ODReleaseObject(ev, menuOwner);

        CATCH_ALL
            ODSafeReleaseObject(menuOwner);
        ENDTRY

    SOM_CATCH_ALL
    SOM_ENDTRY
}

//------------------------------------------------------------------------------
// Method:        HandleMenuEvent
// Origin:        SamplePart
//
// Description:    This method is called by the part when a menu event is
//                received.
//
//                Using the menu bar object, we determine what the menu
//                command is, and call the appropriate method to handle
//                it.
//------------------------------------------------------------------------------

SOM_Scope    ODBoolean
SOMLINK        SamplePart__HandleMenuEvent
            (
                SampleCode_SamplePart*        somSelf,
                Environment*                ev,
                ODEventData*                event,
                ODFrame*                    frame
            )
{
    ODBoolean eventHandled = kODTrue;

    SampleCode_SamplePartMethodDebug("SamplePart","HandleMenuEvent");

    SOM_TRY

        ODULong        menuResult    = event->message;
        ODUShort    menu        = HiWord(menuResult);
        ODUShort    item        = LoWord(menuResult);

        switch( ODMenuBar_GetCommand(gGlobals->fMenuBar, ev, menu, item) ) {

            case kODCommandAbout:
                    _DoDialogBox(somSelf, ev, frame, kAboutBoxID, 0);
                    CHECK_ENV(ev);
                    break;

            case kODCommandViewAsWin:
                    SamplePart__Open(somSelf, ev, frame);
                    CHECK_ENV(ev);
                    break;

            // Other commands a part might handle.
            case kODCommandOpen:
            case kODCommandInsert:
            case kODCommandPageSetup:
            case kODCommandPrint:
            case kODCommandUndo:
            case kODCommandRedo:
            case kODCommandCut:
            case kODCommandCopy:
            case kODCommandPaste:
            case kODCommandPasteAs:
            case kODCommandClear:
            case kODCommandSelectAll:
            case kODCommandGetPartInfo:
            case kODCommandPreferences:

            default:
                eventHandled = kODFalse;
        }
        CHECK_ENV(ev);

    SOM_CATCH_ALL
        eventHandled = kODFalse;
    SOM_ENDTRY

    return eventHandled;
}

//------------------------------------------------------------------------------
// Method:        HandleMouseEvent
// Origin:        SamplePart
//
// Description:    This method is called by the part when a mouse event
//                is recieved.
//
//                A typical part would determine the event type(up/down)
//                and respond appropriately, but we have no "real"
//                content model, so we activate the part as appropriate
//                and call a generic method to handle the event.
//
// Remember:    When a frame is inactive, the first mouse up event
//                should activate it; inactive frames do not recieve
//                kODEvtMouseDown events.
//------------------------------------------------------------------------------

SOM_Scope    ODBoolean
SOMLINK        SamplePart__HandleMouseEvent
            (
                SampleCode_SamplePart*        somSelf,
                Environment*                ev,
                ODEventData*                event,
                ODFacet*                    facet,
                ODEventInfo*                eventInfo
            )
{
    SampleCode_SamplePartMethodDebug("SamplePart","HandleMouseEvent");

    SOM_TRY

        // If the facet parameter is invalid, the mousedown occurred outside the
        // bounds of a Modal window, otherwise it should be treated normally.

        if ( facet != kODNULL )
        {
            if ( event->what == kODEvtMouseUp )
            {
                ODWindow* window = ODFacet_GetWindow(facet, ev);
                CHECK_ENV(ev);

                // Activate inactive windows on the first mouse up/down event.
                if ( !ODWindow_IsActive(window, ev) )
                {
                    ODWindow_Select(window, ev);
                    CHECK_ENV(ev);
                }
                // Activate the frame (if needed) on all mouse up/down events.
                else
                {
                    CFrameInfo* frameInfo = kODNULL;
                    // Get our state information from the PartInfo of the frame.
                    ODFrame* frame = ODFacet_GetFrame(facet, ev);
                    CHECK_ENV(ev);
                    frameInfo = (CFrameInfo*) ODFrame_GetPartInfo(frame, ev);

                    // If this frame is not the active one, activate it by requesting
                    // the appropriate foci.

                    if ( !CFrameInfo_IsFrameActive(frameInfo) )
                    {
                        if ( _ActivateFrame(somSelf, ev, frame) )
                        {
                            // Keep track of which facet was the last active for positioning
                            // part windows.
                            CFrameInfo_SetActiveFacet(frameInfo, facet);
                        }
                        else
                            // We were unable to acquire the necessary focus and activate it.
                            return kODFalse;

                        CHECK_ENV(ev);
                    }
                }
                CHECK_ENV(ev);
            }
            else if  ( event->what == kODEvtMouseDown )
            {
                Point where;

                // Get the localized mouse coordinates from the Event Info.
                where.h = FixedToInt(eventInfo->where.x);
                where.v = FixedToInt(eventInfo->where.y);

                // Handle the mouse down event.
                _DoMouseEvent(somSelf, ev, facet, &where);
                CHECK_ENV(ev);
            }
        }
        else
        {
            // User clicked outside the bounds of a Modal window, though we actually
            // never display one.

            SysBeep(1);
        }

    SOM_CATCH_ALL
    SOM_ENDTRY

    return kODTrue;
}

//------------------------------------------------------------------------------
// Method:        DoMouseEvent
// Origin:        SamplePart
//
// Description:    This method is called by the part to handle mouse
//                events.
//------------------------------------------------------------------------------

SOM_Scope    void
SOMLINK        SamplePart__DoMouseEvent
            (
                SampleCode_SamplePart*        somSelf,
                Environment*                ev,
                ODFacet*                    facet,  /* unused */
                Point*                        where /* unused */
            )
{
    SampleCode_SamplePartMethodDebug("SamplePart","DoMouseEvent");

    // If you part allows selections or a lasso tool, this is where you
    // would handle those events. This is also where you would handle
    // program controlled buttons or controls.
}

//--------------------------------------------------------------------
// Method:        DoDialogBox
// Origin:        SamplePart
//
// Description:    This method is called by the part when a dialog needs to be
//                displayed (ie. the About Box). If a valid error number is passed
//                in, an error dialog will be displayed.
//-------------------------------------------------------------------

SOM_Scope    void
SOMLINK        SamplePart__DoDialogBox
             (
                SampleCode_SamplePart*        somSelf,
                Environment*                ev,
                ODFrame*                    frame,
                ODSShort                    dialogID,
                ODUShort                    errorNumber
            )
{
    SampleCode_SamplePartData *somThis = SampleCode_SamplePartGetData(somSelf);
    SampleCode_SamplePartMethodDebug("SamplePart","DoAboutBox");

    SOM_TRY

        CFrameProxy*    proxy;
        ODFrame*         focusFrame = frame;
        CLink*            link;
        ODSession*        session;
        ODArbitrator*    arbitrator;

        // If the calling method does not have a frame available to it, we need to
        // locate a frame to use for requesting the modal focus. Find the first valid
        // frame in our display frames list.
        if ( focusFrame == kODNULL )
        {
            for ( link = CLinkedList_First(_fDisplayFrames);
                 CLink_Content(link);
                 link = CLink_Next(link) )
            {
                proxy = (CFrameProxy*) CLink_Content(link);
                if (CFrameProxy_FrameIsLoaded(proxy, ev))
                    focusFrame = CFrameProxy_GetFrame(proxy,ev);
                CHECK_ENV(ev);
                if ( focusFrame ) break;
            }
        }

        // Our About box is modal so we must request the Modal focus to prevent
        // multiple modal dialogs being displayed simultaneously.

        session = ODGetSessionFromPart(ev,_fSelf);
        CHECK_ENV(ev);
        arbitrator = ODSession_GetArbitrator(session, ev);
        CHECK_ENV(ev);

        if ( ODArbitrator_RequestFocus(arbitrator, ev, gGlobals->fModalFocus,frame) )
        {
            DialogPtr    dialog;
            ODSShort    itemHit;
            ODSLong     rfRef;

            // Dim the frontmost document window.
            ODWindowState* windowState = ODSession_GetWindowState(session, ev);
            ODWindowState_DeactivateFrontWindows(windowState, ev);
            CHECK_ENV(ev);

            rfRef = BeginUsingLibraryResources();
            {
                dialog = GetNewDialog(dialogID, kODNULL, (WindowPtr) -1L);

                if ( dialog )
                {
                    if ( errorNumber > 0 )
                    {
                        Handle    itemHandle;
                        Rect    itemRect;
                        short    itemType;
                        Str255    errStr;

                        GetIndString(errStr, kErrorStringResID, errorNumber);
                        GetDialogItem(dialog, kErrStrFieldID, &itemType, &itemHandle, &itemRect);
                        SetDialogItemText(itemHandle, errStr);

                        // We don't need the cancel button for an error dialog.
                        HideDialogItem(dialog, cancel);

                        SetDialogDefaultItem(dialog, ok);
                    }

                    SetCursor(&ODQDGlobals.arrow);
                    ShowWindow(dialog);
                    ModalDialog(kODNULL, &itemHit);
                    DisposeDialog(dialog);
                }
                else
                {
                    // Could not load About box dialog... something is amiss.
                    SysBeep(2);
                }
            }
            EndUsingLibraryResources(rfRef);

            // Inform the Arbitrator that we no longer require the Modal focus.
            ODArbitrator_RelinquishFocus(arbitrator, ev, gGlobals->fModalFocus,frame);
            CHECK_ENV(ev);

            // Hilite the frontmost document window.
            ODWindowState_ActivateFrontWindows(windowState, ev);
            CHECK_ENV(ev);
        }
        else
            // If we can't get the modal focus, then another modal dialog is
            // already being displayed.
            SysBeep(2);
        CHECK_ENV(ev);

    SOM_CATCH_ALL
    SOM_ENDTRY
}


//==============================================================================
#pragma mark    • Stubbed Methods •
//==============================================================================

#include "SamplePartStubs.c"